Intisari
Anda berhenti mengawasi agen AI dengan membangun tiga hal: pagar pengaman (kendala yang mencegah kegagalan fatal), observabilitas (log dan metrik yang memberi tahu Anda apa yang terjadi), dan pos pemeriksaan (jeda otomatis di mana manusia memverifikasi keputusan). Setelah ini diatur, agen Anda dapat berjalan secara mandiri selama berjam-jam, bukan hanya beberapa menit. Alat seperti Apidog membantu dengan memungkinkan Anda menentukan kontrak API yang tidak dapat dilanggar oleh agen, mengubah lapisan API Anda menjadi jaring pengaman.
Pendahuluan
Minggu lalu saya melihat seorang pengembang menghabiskan 4 jam mengawasi agen AI yang seharusnya menghemat waktunya. Setiap beberapa menit, dia akan menginterupsi, memperbaiki kesalahan, dan memulai ulang. Pada akhirnya, dia melakukan lebih banyak pekerjaan manual daripada jika dia menulis kodenya sendiri.
Ini adalah masalah pengawasan, dan ini adalah alasan #1 mengapa agen AI gagal memenuhi janjinya. Alatnya berfungsi. Modelnya mampu. Tetapi sebagian besar tim tidak pernah melewati fase pengawasan terus-menerus.
Inilah yang terjadi: sebagian besar pengaturan agen AI memperlakukan LLM seperti pengembang junior yang membutuhkan bimbingan untuk setiap tugas. Tetapi LLM bukanlah junior. Mereka lebih seperti magang yang sangat cepat, terkadang berhalusinasi, yang akan dengan percaya diri melakukan hal yang salah jika Anda tidak menetapkan batasan.
Definisikan kontrak API yang dapat diikuti agen AI Anda
Pada akhir panduan ini, Anda akan memiliki:
- Model mental untuk memikirkan otonomi agen
- Pola konkret untuk pagar pengaman, observabilitas, dan pos pemeriksaan
- Contoh kode yang dapat Anda salin ke proyek Anda hari ini
- Daftar periksa untuk mengevaluasi apakah agen siap berjalan tanpa pengawasan
Mengapa agen memerlukan pengawasan terus-menerus
Agen AI gagal dengan cara yang dapat diprediksi. Memahami mode kegagalan ini adalah langkah pertama untuk memperbaikinya.
Mode Kegagalan 1: Pelebaran ruang lingkup
Anda meminta agen untuk “menambahkan autentikasi ke titik akhir API.” Agen menambahkan autentikasi. Kemudian menambahkan pembatasan laju. Lalu refaktor skema basis data. Lalu menghapus apa yang dianggapnya sebagai file "tidak terpakai", yang ternyata penting.
Agen terus berjalan karena tidak ada yang menyuruhnya berhenti. LLM tidak memiliki pengertian "selesai" yang bawaan. Mereka akan terus melakukan perubahan sampai mereka mencapai batas token atau Anda menginterupsi mereka.
Mode Kegagalan 2: Abstraksi yang salah
Agen yang bertugas "meningkatkan penanganan kesalahan" mungkin akan menambahkan blok try-catch di mana-mana. Secara teknis benar. Secara praktis mengerikan. Kode menjadi tidak terbaca, pencatatan tidak konsisten, dan kasus kesalahan yang sebenarnya tidak ditangani.
Agen memahami permintaan secara harfiah tetapi melewatkan maksudnya. Tanpa contoh penanganan kesalahan yang baik, ia mengasumsikan interpretasi yang paling jelas (dan terburuk).
Mode Kegagalan 3: Kegagalan berjenjang
Agen membuat kesalahan kecil di langkah 1. Pada langkah 10, kesalahan itu telah menyebar melalui setiap keputusan berikutnya. Apa yang dimulai sebagai salah ketik dalam nama fungsi menjadi API yang rusak, tes yang rusak, dan pengembang yang bingung mencoba mencari tahu apa yang salah.
Ini adalah mode kegagalan yang paling berbahaya karena agen tidak tahu bahwa itu gagal. Setiap langkah tampak masuk akal secara terpisah. Hanya hasil akhir yang menunjukkan masalahnya.
Mode Kegagalan 4: Kelelahan sumber daya
Tanpa pengawasan, beberapa agen akan berulang tanpa henti. Mereka akan mencoba kembali panggilan API yang gagal tanpa batas, membuat sub-agen baru tanpa batas, atau terus menghasilkan kode hingga mencapai batas tagihan Anda.
Tanpa batasan sumber daya, agen tidak tahu kapan harus berhenti.
Kerangka otonomi: pagar pengaman, observabilitas, pos pemeriksaan
Anda menyelesaikan masalah ini dengan tiga lapisan. Anggap saja sebagai piramida: pagar pengaman di bagian bawah (mencegah kegagalan), observabilitas di tengah (mendeteksi kegagalan), dan pos pemeriksaan di atas (memulihkan dari kegagalan).
Lapisan 1: Pagar pengaman (pencegahan)
Pagar pengaman adalah batasan yang mencegah kegagalan fatal. Ini adalah aturan yang tidak dapat dilanggar oleh agen Anda, yang ditegakkan oleh kode, bukan oleh prompt.
Batasan keras melalui kode:
# Jangan: Percayai agen untuk mengikuti instruksi
agent.run("Hanya modifikasi file di direktori src/")
# Lakukan: Terapkan batasan dalam kode
import os
from pathlib import Path
ALLOWED_DIRECTORIES = {"src", "tests", "docs"}
def validate_file_path(path: str) -> bool:
"""Agen tidak dapat menulis di luar direktori yang diizinkan."""
abs_path = Path(path).resolve()
return any(
str(abs_path).startswith(str(Path(d).resolve()))
for d in ALLOWED_DIRECTORIES
)
# Gunakan dalam operasi file agen Anda
def agent_write_file(path: str, content: str):
if not validate_file_path(path):
raise ValueError(f"Tidak dapat menulis ke {path}: di luar direktori yang diizinkan")
with open(path, 'w') as f:
f.write(content)
Batasan skema API:
Saat agen Anda memanggil API, gunakan skema untuk mencegah permintaan yang salah bentuk. Di sinilah Apidog sangat berguna. Tentukan kontrak API Anda sekali, dan agen Anda tidak dapat mengirim bentuk data yang salah.
// apidog-schema.ts
export const CreateUserSchema = {
type: 'object',
required: ['email', 'name'],
properties: {
email: { type: 'string', format: 'email' },
name: { type: 'string', minLength: 1, maxLength: 100 },
role: { type: 'string', enum: ['user', 'admin', 'guest'] }
},
additionalProperties: false
}
// Agen harus memvalidasi sebelum memanggil API
function validateRequest(schema: object, data: unknown): void {
const valid = ajv.validate(schema, data)
if (!valid) {
throw new Error(`Permintaan tidak valid: ${JSON.stringify(ajv.errors)}`)
}
}
Batasan anggaran:
import time
from dataclasses import dataclass
@dataclass
class AgentBudget:
max_steps: int = 50
max_tokens: int = 100000
max_time_seconds: int = 600 # 10 menit
max_api_calls: int = 100
class BudgetEnforcer:
def __init__(self, budget: AgentBudget):
self.budget = budget
self.start_time = time.time()
self.steps = 0
self.tokens_used = 0
self.api_calls = 0
def check(self) -> bool:
"""Mengembalikan False jika anggaran terlampaui."""
elapsed = time.time() - self.start_time
if self.steps >= self.budget.max_steps:
raise RuntimeError(f"Batas langkah tercapai: {self.steps}")
if self.tokens_used >= self.budget.max_tokens:
raise RuntimeError(f"Batas token tercapai: {self.tokens_used}")
if elapsed >= self.budget.max_time_seconds:
raise RuntimeError(f"Batas waktu tercapai: {elapsed:.0f}s")
if self.api_calls >= self.budget.max_api_calls:
raise RuntimeError(f"Batas panggilan API tercapai: {self.api_calls}")
return True
def record_step(self, tokens: int, api_calls: int = 0):
self.steps += 1
self.tokens_used += tokens
self.api_calls += api_calls
self.check()
Lapisan 2: Observabilitas (deteksi)
Ketika agen berjalan selama berjam-jam, Anda perlu tahu apa yang mereka lakukan tanpa harus mengawasi setiap langkah. Observabilitas memberi Anda garis waktu keputusan.
Pencatatan terstruktur:
import json
from datetime import datetime
from typing import Any
class AgentLogger:
def __init__(self, log_file: str = "agent_trace.jsonl"):
self.log_file = log_file
self.entries = []
def log(self, event: str, data: dict[str, Any] | None = None):
entry = {
"timestamp": datetime.utcnow().isoformat(),
"event": event,
"data": data or {}
}
self.entries.append(entry)
# Tambahkan ke file segera (jangan kehilangan log saat crash)
with open(self.log_file, 'a') as f:
f.write(json.dumps(entry) + '\n')
def log_decision(self, decision: str, reasoning: str, confidence: float):
"""Catat saat agen membuat keputusan penting."""
self.log("decision", {
"decision": decision,
"reasoning": reasoning,
"confidence": confidence
})
def log_action(self, action: str, params: dict, result: str):
"""Catat tindakan agen dan hasilnya."""
self.log("action", {
"action": action,
"params": params,
"result": result[:200] # Pangkas hasil yang panjang
})
def log_error(self, error: str, context: dict):
"""Catat kesalahan dengan konteks penuh."""
self.log("error", {
"error": error,
"context": context
})
# Penggunaan dalam agen
logger = AgentLogger()
logger.log_decision(
decision="Tambahkan pembatasan laju ke API",
reasoning="Endpoint saat ini tidak memiliki perlindungan terhadap penyalahgunaan",
confidence=0.85
)
logger.log_action(
action="write_file",
params={"path": "src/middleware/rate-limit.ts"},
result="Berhasil menulis 45 baris"
)
Dasbor metrik:
Untuk agen yang berjalan lebih lama, Anda menginginkan metrik agregat, bukan hanya log individual.
from collections import Counter
from dataclasses import dataclass, field
@dataclass
class AgentMetrics:
actions_taken: Counter = field(default_factory=Counter)
files_modified: list[str] = field(default_factory=list)
api_calls: dict[str, int] = field(default_factory=dict)
errors: list[str] = field(default_factory=list)
decisions_by_confidence: dict[str, int] = field(default_factory=lambda: {
"tinggi (>0.9)": 0,
"sedang (0.7-0.9)": 0,
"rendah (<0.7)": 0
})
def record_action(self, action: str):
self.actions_taken[action] += 1
def record_file_modification(self, path: str):
if path not in self.files_modified:
self.files_modified.append(path)
def record_api_call(self, endpoint: str):
self.api_calls[endpoint] = self.api_calls.get(endpoint, 0) + 1
def record_error(self, error: str):
self.errors.append(error)
def record_decision(self, confidence: float):
if confidence > 0.9:
self.decisions_by_confidence["tinggi (>0.9)"] += 1
elif confidence >= 0.7:
self.decisions_by_confidence["sedang (0.7-0.9)"] += 1
else:
self.decisions_by_confidence["rendah (<0.7)"] += 1
def summary(self) -> str:
return f"""
Ringkasan Metrik Agen
=====================
Tindakan: {dict(self.actions_taken)}
File diubah: {len(self.files_modified)}
Panggilan API: {self.api_calls}
Kesalahan: {len(self.errors)}
Keputusan berdasarkan kepercayaan diri: {self.decisions_by_confidence}
"""
Lapisan 3: Pos pemeriksaan (pemulihan)
Pos pemeriksaan adalah jeda otomatis di mana agen menunggu verifikasi manusia. Ini memungkinkan Anda menangkap masalah sejak dini tanpa pengawasan terus-menerus.
Pos pemeriksaan otomatis:
from enum import Enum
from typing import Callable
class CheckpointTrigger(Enum):
BEFORE_FILE_WRITE = "sebelum_menulis_file"
BEFORE_API_CALL = "sebelum_memanggil_api"
BEFORE_GIT_COMMIT = "sebelum_git_commit"
BEFORE_DELETE = "sebelum_menghapus"
AFTER_N_STEPS = "setelah_n_langkah"
@dataclass
class Checkpoint:
trigger: CheckpointTrigger
description: str
data: dict
requires_approval: bool = True
class CheckpointManager:
def __init__(self, auto_approve: set[CheckpointTrigger] | None = None):
self.auto_approve = auto_approve or set()
self.pending: list[Checkpoint] = []
def create_checkpoint(
self,
trigger: CheckpointTrigger,
description: str,
data: dict
) -> bool:
"""Mengembalikan True jika disetujui, False jika ditolak."""
# Otomatis menyetujui pemicu tertentu
if trigger in self.auto_approve:
return True
checkpoint = Checkpoint(
trigger=trigger,
description=description,
data=data
)
self.pending.append(checkpoint)
# Dalam sistem nyata, ini akan memberitahukan manusia dan menunggu
# Untuk saat ini, kami mengembalikan False untuk menghentikan eksekusi
return False
def approve(self, checkpoint_id: int) -> None:
"""Manusia menyetujui pos pemeriksaan yang tertunda."""
if 0 <= checkpoint_id < len(self.pending):
self.pending.pop(checkpoint_id)
def reject(self, checkpoint_id: int) -> None:
"""Manusia menolak pos pemeriksaan yang tertunda."""
raise RuntimeError(f"Pos pemeriksaan ditolak: {self.pending[checkpoint_id]}")
# Penggunaan dalam agen
checkpoints = CheckpointManager(
auto_approve={CheckpointTrigger.BEFORE_FILE_WRITE} # Percayakan penulisan file
)
# Sebelum tindakan destruktif
if not checkpoints.create_checkpoint(
trigger=CheckpointTrigger.BEFORE_DELETE,
description="Akan menghapus direktori src/legacy/",
data={"path": "src/legacy/", "files": ["old_handler.ts", "deprecated.ts"]}
):
# Tunggu persetujuan manusia
agent.pause("Menunggu persetujuan untuk menghapus file")
Membangun agen otonom dengan Apidog
Ketika agen AI Anda berinteraksi dengan API, risiko terbesar adalah permintaan yang salah bentuk yang menyebabkan kegagalan hilir. Apidog membantu dengan memungkinkan Anda menentukan skema API yang tepat yang harus diikuti oleh agen Anda.
Menyiapkan kontrak API:
- Impor atau definisikan spesifikasi OpenAPI Anda di Apidog
- Hasilkan kode klien dengan validasi bawaan
- Berikan agen Anda klien yang divalidasi daripada HTTP mentah
// Alih-alih membiarkan agen memanggil API secara langsung
const response = await fetch('/api/users', {
method: 'POST',
body: JSON.stringify(data) // Tanpa validasi
})
// Beri agen klien yang divalidasi
import { UsersApi } from './generated/apidog-client'
const usersApi = new UsersApi()
// Agen hanya dapat mengirim permintaan yang valid - skema ditegakkan
const response = await usersApi.createUser({
email: 'user@example.com',
name: 'Test User',
role: 'user' // Harus merupakan nilai enum yang valid
})
Ini mengubah lapisan API Anda menjadi pagar pengaman. Agen secara harfiah tidak dapat mengirim data yang tidak valid karena klien menolaknya sebelum permintaan keluar.
Hasilkan klien API yang divalidasi untuk agen AI Anda
Pola yang terbukti dan kesalahan umum
Pola 1: Sandwich persetujuan
Untuk operasi berisiko, mintalah persetujuan sebelum DAN sesudah.
def risky_operation(agent, operation):
# Pra-persetujuan
if not agent.checkpoint(f"Akan melakukan: {operation.description}"):
return "Dibatalkan oleh pengguna"
# Lakukan operasi
result = operation.execute()
# Pasca-persetujuan (verifikasi hasilnya)
if not agent.checkpoint(f"Verifikasi hasil dari: {operation.description}"):
operation.rollback()
return "Digulirkan kembali oleh pengguna"
return result
Pola 2: Ambang kepercayaan diri
Jangan biarkan agen bertindak berdasarkan keputusan dengan tingkat kepercayaan diri rendah.
MIN_CONFIDENCE = 0.75
def agent_decide(options: list[dict]) -> dict:
best = max(options, key=lambda x: x.get('confidence', 0))
if best['confidence'] < MIN_CONFIDENCE:
# Eskalasi ke manusia
return {
'action': 'escalate',
'reason': f"Opsi terbaik memiliki kepercayaan diri {best['confidence']:.2f} < {MIN_CONFIDENCE}",
'options': options
}
return best
Pola 3: Operasi Idempoten
Rancang tindakan agen Anda agar dapat diulang tanpa efek samping.
import hashlib
def idempotent_write(path: str, content: str) -> bool:
"""Hanya tulis jika konten berubah."""
content_hash = hashlib.sha256(content.encode()).hexdigest()
existing_hash = None
if os.path.exists(path):
with open(path, 'r') as f:
existing_hash = hashlib.sha256(f.read().encode()).hexdigest()
if content_hash == existing_hash:
logger.log_action("write_file", {"path": path}, "Dilewati - tidak ada perubahan")
return False
with open(path, 'w') as f:
f.write(content)
logger.log_action("write_file", {"path": path}, f"Menulis {len(content)} byte")
return True
Kesalahan umum yang harus dihindari
Percaya pada prompt sebagai batasan. "Jangan hapus file" dalam prompt bukanlah batasan. Izin file adalah batasan.
Tidak ada rencana pemulihan. Ketika agen membuat kesalahan, Anda perlu membatalkannya. Jika Anda tidak menggunakan git atau cadangan, Anda mempercayai agen dengan tindakan yang tidak dapat dipulihkan.
Mengabaikan skor kepercayaan. Sebagian besar LLM mengeluarkan kepercayaan atau dapat dipromosikan untuk itu. Kepercayaan rendah = jeda dan tanyakan manusia.
Pengawasan berlebihan. Jika Anda mengawasi setiap langkah, Anda belum membangun sistem otonom. Anda telah membangun sistem manual yang lambat.
Kurangnya spesifikasi keberhasilan. Agen perlu tahu kapan ia selesai. "Perbaiki bug" tidak memiliki kondisi akhir. "Perbaiki bug DAN semua tes lulus" memiliki kondisi akhir.
Alternatif dan perbandingan
| Pendekatan | Otonomi | Risiko | Terbaik untuk |
|---|---|---|---|
| Pengkodean manual | Tidak ada | Rendah | Pekerjaan kompleks, kritis |
| Pemrograman berpasangan dengan AI | Rendah | Rendah | Pembelajaran, eksplorasi |
| Agen yang diawasi | Sedang | Sedang | Tugas rutin |
| Agen otonom dengan pagar pengaman | Tinggi | Terkontrol | Operasi massal, migrasi |
| Agen otonom penuh | Sangat tinggi | Tinggi | Alur kerja terpercaya, teruji dengan baik |
Sebagian besar tim harus bertujuan untuk "otonom dengan pagar pengaman." Ini adalah titik manis di mana Anda mendapatkan 80% penghematan waktu dengan 10% risiko.
Kasus penggunaan dunia nyata
Migrasi basis kode. Sebuah tim menggunakan agen otonom untuk memigrasi 200 titik akhir API dari REST ke GraphQL. Pagar pengaman mencegah perubahan skema. Pos pemeriksaan memerlukan persetujuan sebelum menghapus titik akhir lama. Migrasi memakan waktu 3 hari alih-alih 3 minggu, tanpa insiden produksi.
Pembuatan dokumentasi. Agen secara otomatis menghasilkan dokumen API dari kode. Pagar pengaman memastikan agen hanya membaca dari direktori tertentu. Pos pemeriksaan menjeda sebelum publikasi. Tim meninjau seminggu sekali alih-alih menulis dokumen secara manual.
Cakupan pengujian. Agen menganalisis kode dan menulis pengujian yang hilang. Batasan anggaran mencegah pembuatan pengujian yang tidak terkontrol. Ambang kepercayaan menandai pengujian yang tidak pasti untuk ditinjau oleh manusia. Cakupan meningkat dari 60% menjadi 85% dalam satu bulan.
Ringkasan
Berikut adalah apa yang telah Anda pelajari:
- Agen AI gagal dengan cara yang dapat diprediksi: pelebaran ruang lingkup, abstraksi yang salah, kegagalan berjenjang, kelelahan sumber daya
- Tiga lapisan memecahkan sebagian besar masalah: pagar pengaman (pencegahan), observabilitas (deteksi), pos pemeriksaan (pemulihan)
- Pagar pengaman adalah kode, bukan prompt. Terapkan batasan secara terprogram.
- Observabilitas berarti log dan metrik terstruktur, bukan mengawasi setiap langkah
- Pos pemeriksaan memungkinkan manusia memverifikasi keputusan tanpa pengawasan terus-menerus
- Skema API dari Apidog mengubah lapisan API Anda menjadi pagar pengaman
Langkah Anda selanjutnya:
- Identifikasi tugas yang paling berulang yang dibantu AI
- Tentukan pagar pengaman: apa yang tidak boleh dilakukan agen?
- Tambahkan pencatatan terstruktur untuk melihat apa yang terjadi
- Buat pos pemeriksaan untuk operasi berisiko tinggi
- Biarkan berjalan selama 30 menit dan periksa lognya
Tujuannya bukan untuk menghilangkan manusia dari lingkaran. Ini adalah menempatkan manusia di tempat yang tepat dalam lingkaran: membuat keputusan tingkat tinggi daripada mengoreksi kesalahan tingkat rendah.
Bangun pagar pengaman API untuk agen AI Anda - gratis
FAQ
Apa perbedaan antara agen AI dan asisten AI?Asisten merespons permintaan Anda dan menunggu instruksi Anda berikutnya. Agen mengambil tujuan dan secara otonom merencanakan serta melaksanakan langkah-langkah untuk mencapainya. Asisten membutuhkan Anda di setiap putaran. Agen berjalan hingga mencapai pos pemeriksaan atau selesai.
Bagaimana saya tahu jika agen saya siap untuk berjalan secara otonom?Jalankan dalam mode diawasi selama 10 sesi. Catat setiap kali Anda harus campur tangan. Jika intervensi turun di bawah 2 per sesi dan semuanya kecil (klarifikasi, bukan koreksi), agen sudah siap. Jika intervensi sering atau memerlukan pembatalan pekerjaan, tambahkan lebih banyak pagar pengaman.
Apa risiko terbesar dengan agen otonom?Kegagalan berjenjang yang tidak dikenali oleh agen. Kesalahan kecil di awal menjadi masalah besar di kemudian hari, dan agen terus berjalan karena setiap langkah tampak masuk akal secara terpisah. Pos pemeriksaan memutus kaskade ini dengan memaksakan verifikasi.
Dapatkah saya menggunakan pola ini dengan LLM apa pun?Ya. Pola-pola ini (pagar pengaman, observabilitas, pos pemeriksaan) adalah agnostik model. Mereka berfungsi dengan Claude, GPT-4, Gemini, atau model lainnya. Detail implementasi spesifik mungkin bervariasi, tetapi konsepnya dapat diterapkan.
Seberapa besar observabilitas memperlambat agen?Dapat diabaikan. Menulis ke file log membutuhkan mikrodiketik. Perlambatan berasal dari pos pemeriksaan yang menunggu input manusia. Untuk jalankan yang benar-benar otonom, Anda hanya melakukan pos pemeriksaan pada saat-saat berisiko tinggi, bukan setiap langkah.
Bagaimana jika agen membuat keputusan yang saya tidak setujui?Itulah gunanya pos pemeriksaan. Ketika Anda melihat keputusan yang tidak Anda setujui, tolak pos pemeriksaan tersebut. Agen akan membatalkan atau mencoba pendekatan yang berbeda. Lebih baik: sertakan preferensi Anda dalam instruksi agen agar ia belajar gaya Anda seiring waktu.
Haruskah saya memulai dengan agen yang diawasi atau otonom?Selalu mulai dengan diawasi. Jalankan agen dengan pos pemeriksaan pada setiap tindakan signifikan sampai Anda mempercayainya. Secara bertahap hapus pos pemeriksaan untuk tindakan berisiko rendah. Ini membangun kepercayaan secara bertahap daripada mengambil risiko kegagalan fatal pada jalankan otonom pertama Anda.
Bagaimana Apidog secara spesifik membantu agen AI?Apidog menghasilkan klien API yang divalidasi dari skema Anda. Ketika agen menggunakan klien ini, permintaan yang salah bentuk akan ditolak sebelum mencapai backend Anda. Ini mencegah seluruh kelas kegagalan di mana agen mengirimkan bentuk data yang salah atau nilai yang tidak valid.