Halaman ini adalah terjemahan mesin dan belum sepenuhnya ditinjau. Teks asli berbahasa Inggris adalah acuan yang berlaku. Pernyataan tentang keamanan, privasi, penanganan data, kepatuhan, dan lisensi tetap dalam bahasa Inggris sampai peninjau teknis menyetujuinya. Baca teks asli berbahasa Inggris

Mulai Cepat

Mode yang didukung: Hosted Hybrid Local Tersedia di: Free Solo Teams

Tambahkan tata kelola AI ke agen Anda dalam waktu kurang dari 5 menit. Ada dua jalur deployment. Pilih yang sesuai dengan situasi Anda:

Jalur	Terbaik untuk	Perubahan kode
Gateway (Opsi A)	Agen yang sudah ada, rollout cepat	Tidak ada. Ubah satu URL
SDK (Opsi B)	Agen baru, integrasi paling erat	Pasang paket, bungkus pemanggilan alat

Keduanya menerapkan kebijakan yang sama yang didefinisikan di dasbor Anda.

Buka app.controlzero.ai dan buat akun.
Ingin menjelajah dulu? Coba demo interaktif di app.controlzero.ai/demo. Tanpa akun.

Paket gratis mencakup 5.000 aksi terkendali per bulan tanpa kartu kredit.

Langkah 2: Buat Proyek

Setelah masuk, onboarding 2 langkah memandu Anda membuat proyek pertama.
Beri nama proyek Anda (misalnya my-agent) dan pilih lingkungan Anda.
Salin API Key Anda dari halaman pengaturan proyek (misalnya cz_live_abc123...).

Setel sebagai variabel lingkungan:

export CONTROLZERO_API_KEY="cz_live_your_key_here"

Langkah 3: Definisikan Kebijakan di Dasbor

Kebijakan berada di tingkat organisasi dalam Policy Library dan dilampirkan ke proyek. Ini memungkinkan satu kebijakan mengendalikan banyak proyek dengan override per proyek.

3a. Buat kebijakan library

Klik Library di sidebar, lalu New policy.

Name: db-read-only
Description: Agen boleh melakukan query ke database tetapi tidak dapat mengubah data.
Rules (JSON array): tempel cuplikan di bawah, atau klik Insert sample.

[
  { "effect": "allow", "actions": ["database:read"], "resources": ["*"] },
  { "effect": "deny", "actions": ["database:write"], "resources": ["*"] },
  { "effect": "deny", "actions": ["database:admin"], "resources": ["*"] }
]

Klik Create & publish v1. Kebijakan disimpan dan otomatis dipublikasikan sebagai versi 1 sehingga langsung dapat dilampirkan.

Bentuk aturan kanonis

actions, resources, dan principals adalah array. Dialog pembuatan menerima bentuk tunggal datar action / resource dari dokumentasi lama dan menormalkannya untuk Anda.

Kelas semantik SQL

database:read adalah kelas kanonis portabel yang mencakup pernyataan SELECT, EXPLAIN, SHOW, DESCRIBE, dan CTE terlepas dari ejaan kata kunci dialeknya. database:write mencakup INSERT/UPDATE/DELETE/MERGE dan pernyataan lain yang mengubah data. database:admin mencakup perubahan skema dan izin. Pernyataan ganda terselubung seperti SELECT 1; DROP TABLE x diselesaikan sebagai database:admin sehingga aturan deny: database:admin menangkapnya di setiap versi yang dipublikasikan. Bentuk hanya-izinkan (tanpa aturan penolakan eksplisit) memerlukan controlzero 1.13.13+ agar SQL destruktif diblokir dengan benar ketika method diberikan; versi sebelumnya mengizinkannya karena kelas turunan-metode dapat memenuhi aturan allow sebelum kelas turunan-argumen diperiksa. Anda tetap dapat menargetkan kata kunci tertentu (misalnya database:DROP) bila memerlukan kontrol yang lebih halus. Lihat Canonical Tool Names untuk pemetaan lengkapnya.

3b. Lampirkan kebijakan ke proyek Anda

Buka proyek Anda, klik Attach policy, pilih db-read-only, biarkan status sebagai Active, lalu konfirmasi. Bundel kebijakan proyek kini menerapkan aturan tersebut. Klien mengambilnya pada refresh berikutnya: SDK Python melakukan polling setiap 60 detik secara default, SDK Node setiap 300 detik.

Langkah 4: Integrasikan Agen Anda

Opsi A: Gateway (Tanpa Perubahan Kode)

Gateway adalah proxy transparan. Arahkan base URL LLM Anda ke gateway dan tambahkan dua header. Kode agen Anda yang sudah ada tetap berfungsi.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

The gateway enforces policies on every request and response automatically.

1. Ubah Base URL Anda

Anthropic (Claude):

# Before
ANTHROPIC_BASE_URL=https://api.anthropic.com

# After
ANTHROPIC_BASE_URL=https://gateway.controlzero.ai

OpenAI:

# Before
OPENAI_BASE_URL=https://api.openai.com

# After
OPENAI_BASE_URL=https://gateway.controlzero.ai/v1

2. Tambahkan Header Control Zero

Tambahkan header berikut ke setiap permintaan LLM:

X-ControlZero-API-Key: cz_live_your_key_here
X-ControlZero-Agent-ID: my-first-agent

X-ControlZero-API-Key (wajib) adalah kunci proyek Anda dari dasbor.
X-ControlZero-Agent-ID (opsional) memberi label pemanggil untuk atribusi audit. Default-nya <provider>-direct jika dihilangkan.

3. Uji (Anthropic)

curl -X POST https://gateway.controlzero.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "X-ControlZero-API-Key: $CONTROLZERO_API_KEY" \
  -H "X-ControlZero-Agent-ID: my-first-agent" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "What is 2+2?"}]
  }'

Kunci API Anthropic Anda (x-api-key) mengautentikasi ke Anthropic. Kunci API Control Zero Anda (X-ControlZero-API-Key) mengaktifkan tata kelola, pencatatan audit, dan penerapan kebijakan. Keduanya wajib.

Hanya itu. Gateway mengintersepsi setiap respons LLM, mengevaluasi pemanggilan alat terhadap kebijakan Anda, dan memblokir aksi yang tidak diotorisasi. Pemeriksaan pre-flight (pemblokiran model, batas biaya, deteksi PII) berjalan pada setiap permintaan sebelum sampai ke penyedia.

Lihat Panduan Gateway untuk deployment self-hosted, penyedia yang didukung, dan detail konfigurasi.

Opsi B: Integrasi SDK

Pasang SDK untuk mengendalikan pemanggilan alat di tingkat aplikasi.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

With an API key the SDK pulls your signed policy bundle from the dashboard automatically -- no local policy file required.

Panggil guard() sebelum mengeksekusi alat apa pun.

1. Pasang SDK

Python:

pip install controlzero

Persyaratan: Python 3.9 atau lebih baru.

Node.js:

Paket @controlzero disajikan dari registry Control Zero. Arahkan scope ke sana sekali di .npmrc Anda (tingkat proyek atau pengguna):

@controlzero:registry=https://npm.controlzero.ai

Lalu pasang:

npm install @controlzero/sdk

Dependensi di luar scope @controlzero tetap di-resolve dari npmjs.org.

2. Tambahkan Tata Kelola ke Aplikasi AI Anda (Mode Hosted)

Python:

from controlzero import Client

# SDK pulls your dashboard policy on first call. Signed bundle, verified
# locally. Audit streams to the dashboard trail.
cz = Client(api_key="cz_live_your_key_here")

# Policies are managed in app.controlzero.ai, not in code. The SDK
# derives the SQL semantic class (read|write|admin|exec) from the
# `sql` argument, so a `database:read` rule fires for SELECT,
# EXPLAIN, SHOW, and CTE statements regardless of dialect.
result = cz.guard("database", method="SELECT", args={"sql": "SELECT id FROM orders"})
print(result.decision)  # "allow" or "deny" per dashboard rules

result = cz.guard("database", method="DROP", args={"sql": "DROP TABLE orders"})
print(result.decision)  # typically "deny" (matches database:admin)
print(result.reason)

# Or raise on deny:
from controlzero import PolicyDeniedError
try:
    cz.guard("database", method="DROP", args={"sql": "DROP TABLE orders"}, raise_on_deny=True)
except PolicyDeniedError as e:
    print(f"Blocked: {e.decision.reason}")

cz.close()

Node.js:

import { Client } from '@controlzero/sdk';

// Hosted mode uses the async factory. The SDK pulls your dashboard
// policy on first call, verifies signature, decrypts, and enforces.
const cz = await Client.create({ apiKey: 'cz_live_your_key_here' });

const result = cz.guard('database', {
  method: 'SELECT',
  args: { sql: 'SELECT id FROM orders' },
});
console.log(result.decision); // "allow" or "deny"

await cz.close();

Dua mode, satu klien:

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Hosted mode (api_key=...): the SDK pulls the signed policy bundle from the dashboard, verifies and decrypts it locally, and ships audit to the remote trail. Keys and bundles are cached under ~/.controlzero/cache/ so restarts work offline. This is the recommended flow -- policies live where your team can manage them.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Local mode (policy=... or policy_file=...): zero network for policy eval. Audit stays in a rotating local file. Good for air-gapped deployments and controlzero.yaml checked into the repo.

Metode guard() mengembalikan PolicyDecision dengan field decision ("allow" atau "deny") dan reason. Berikan raise_on_deny=True untuk memunculkan PolicyDeniedError alih-alih mengembalikan keputusan penolakan.

Apa yang terjadi saat panggilan diblokir

Ketika pemanggilan guard() mengembalikan keputusan penolakan, Anda dapat memeriksa hasilnya atau memunculkan exception:

from controlzero import Client, PolicyDeniedError

cz = Client(api_key="cz_live_your_key")

# Check the decision object. Note: `database:execute` is a legacy action
# name. The canonical name is `database:write`; both forms match the
# same calls.
result = cz.guard("database", method="execute", args={"sql": "DROP TABLE orders"})
if result.effect == "deny":
    print(f"Blocked: {result.reason}")
    # result.effect = "deny"
    # result.reason = human-readable explanation
    # result.policy_id = which policy matched

# Or raise on deny
try:
    cz.guard("database", method="execute", args={"sql": "DROP TABLE orders"}, raise_on_deny=True)
except PolicyDeniedError as e:
    print(f"Blocked by policy {e.decision.policy_id}: {e.decision.reason}")

Langkah 5: Gunakan Context Manager (Opsional)

Client mendukung protokol context manager, yang memanggil close() saat keluar untuk mem-flush log audit:

from controlzero import Client, PolicyDeniedError

with Client(policy_file="./controlzero.yaml") as cz:
    result = cz.guard(
        "filesystem",
        {"path": "/data/report.csv"},
        method="read_file",
        context={"resource": "/data/report.csv"},
    )
    if result.denied:
        print(f"Access denied: {result.reason}")
    else:
        print(f"Allowed: {result.reason}")

Skenario Tata Kelola Lengkap

Contoh end-to-end berikut menunjukkan agen realistis yang membaca dari database dan mencoba penulisan yang tidak diotorisasi. Penulisan diblokir oleh kebijakan sebelum alat sempat dipanggil.

from controlzero import Client

policy = {
    "rules": [
        {"allow": "database:read", "reason": "Reads are permitted"},
        {"deny": "database:*", "reason": "All other database operations are blocked"},
    ]
}

def run_analyst_agent(cz: Client) -> None:
    # Step 1: check if read is allowed. The SDK derives the SQL
    # semantic class (read) from the `sql` argument, so the
    # `database:read` rule fires.
    read_decision = cz.guard(
        "database",
        {"sql": "SELECT * FROM orders WHERE region = 'APAC'"},
        method="SELECT",
    )
    print(f"Read decision: {read_decision.decision} - {read_decision.reason}")

    # Step 2: check if write is allowed (it will be denied; class is `write`)
    write_decision = cz.guard(
        "database",
        {"sql": "UPDATE orders SET status = 'processed' WHERE region = 'APAC'"},
        method="UPDATE",
    )
    print(f"Write decision: {write_decision.decision} - {write_decision.reason}")

with Client(policy=policy) as cz:
    run_analyst_agent(cz)

Output yang diharapkan:

Read decision: allow - Reads are permitted
Write decision: deny - All other database operations are blocked

Lihat Log Audit

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Every guard() decision, allowed or denied, is automatically logged.

Di dasbor, buka proyek Anda dan klik Audit Log untuk melihat:

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

This is a complete decision trail, not a sample. Each entry records coverage for that event, so “did not run” is distinguishable from “ran and found nothing.”

Timestamp	Tool	Method	Decision	Agent
12:00:01	database	SELECT	allow	agent-analyst
12:00:02	database	UPDATE	deny	agent-analyst

Referensi SDK: Metode Utama

`Client.init()`

def __init__(
    self,
    api_key: str = None,                  # optional, for hosted mode (cz_live_ or cz_test_)
    policy: dict = None,                  # inline policy dict with "rules" key
    policy_file: str = None,              # path to controlzero.yaml policy file
    strict_hosted: bool = False,          # raise on hybrid (API key + local policy) instead of warn
    log_path: str = "./controlzero.log",  # local audit log path
    log_rotation: str = "daily",          # audit log rotation interval
    log_retention: str = "30 days",       # how long to keep rotated logs
    log_compression: str = None,          # compress rotated logs (e.g. "gz")
    log_format: str = "json",             # audit log format
): ...

Urutan resolusi kebijakan: argumen policy=, argumen policy_file=, variabel lingkungan CONTROLZERO_POLICY_FILE, lalu file pertama yang ditemukan otomatis di direktori saat ini (controlzero.yaml, lalu controlzero.yml, lalu controlzero.json -- yang pertama ada yang dipakai), lalu variabel lingkungan CONTROLZERO_API_KEY (mode hosted), kemudian no-op pass-through. File kebijakan dapat berupa YAML atau JSON; keduanya menggunakan skema yang identik.

`Client.guard(tool, args, method, raise_on_deny, context)`

Mengevaluasi pemanggilan alat terhadap kebijakan yang dimuat. Mengembalikan PolicyDecision dengan field decision ("allow" atau "deny"), reason, dan policy_id. String aksi yang dievaluasi adalah "{tool}:{method}".

Berikan raise_on_deny=True untuk memunculkan PolicyDeniedError pada keputusan penolakan alih-alih mengembalikannya.

`Client.close()`

Mem-flush log audit yang di-buffer dan menutup koneksi yang masih terbuka.

`PolicyDeniedError`

Dimunculkan oleh guard() ketika raise_on_deny=True dan kebijakan menolak aksi tersebut.

Atribut	Tipe	Deskripsi
`e.decision.effect`	`str`	Selalu `"deny"`.
`e.decision.reason`	`str`	Penjelasan yang dapat dibaca manusia.
`e.decision.policy_id`	`str`	ID kebijakan yang cocok, atau `None`.

Debugging

Setel CZ_DEBUG=1 untuk mengaktifkan output debug verbose di stderr. Ini mencetak setiap evaluasi kebijakan, cache hit/miss, dan flush log audit untuk membantu mendiagnosis masalah tata kelola:

CZ_DEBUG=1 python my_agent.py

Contoh output debug:

[CZ DEBUG] initialized client agent=my-agent project=proj_abc123
[CZ DEBUG] policy_eval tool=database method=SELECT action=database:SELECT class=database:read effect=allow policy_id=db-read-only latency_ms=0.12
[CZ DEBUG] policy_eval tool=database method=UPDATE action=database:UPDATE class=database:write effect=deny policy_id=db-read-only latency_ms=0.08
[CZ DEBUG] audit_flush count=2 status=ok

Field latency_ms menunjukkan waktu evaluasi kebijakan.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Policy evaluation is local and does not make network requests.

Langkah Berikutnya

Proxy Gateway: Deployment self-hosted, semua penyedia yang didukung, dan referensi konfigurasi.
Kebijakan: Pelajari cara menulis kebijakan: wildcard, kondisi, urutan evaluasi.
Server MCP: Kelola tata kelola dari klien coding AI.
Mengendalikan pemanggilan alat MCP: Kendalikan akses server dan alat MCP.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Secrets Management: Store provider keys in the encrypted vault.

Referensi SDK: Python: Dokumentasi lengkap SDK Python.

Langkah 1: Daftar​

Langkah 2: Buat Proyek​

Langkah 3: Definisikan Kebijakan di Dasbor​

3a. Buat kebijakan library​

3b. Lampirkan kebijakan ke proyek Anda​

Langkah 4: Integrasikan Agen Anda​

Opsi A: Gateway (Tanpa Perubahan Kode)​

1. Ubah Base URL Anda​

2. Tambahkan Header Control Zero​

3. Uji (Anthropic)​

Opsi B: Integrasi SDK​

1. Pasang SDK​

2. Tambahkan Tata Kelola ke Aplikasi AI Anda (Mode Hosted)​

Apa yang terjadi saat panggilan diblokir​

Langkah 5: Gunakan Context Manager (Opsional)​

Skenario Tata Kelola Lengkap​

Lihat Log Audit​

Referensi SDK: Metode Utama​

Client.__init__()​

Client.guard(tool, args, method, raise_on_deny, context)​

Client.close()​

PolicyDeniedError​

Debugging​

Langkah Berikutnya​

Langkah 1: Daftar

Langkah 2: Buat Proyek

Langkah 3: Definisikan Kebijakan di Dasbor

3a. Buat kebijakan library

3b. Lampirkan kebijakan ke proyek Anda

Langkah 4: Integrasikan Agen Anda

Opsi A: Gateway (Tanpa Perubahan Kode)

1. Ubah Base URL Anda

2. Tambahkan Header Control Zero

3. Uji (Anthropic)

Opsi B: Integrasi SDK

1. Pasang SDK

2. Tambahkan Tata Kelola ke Aplikasi AI Anda (Mode Hosted)

Apa yang terjadi saat panggilan diblokir

Langkah 5: Gunakan Context Manager (Opsional)

Skenario Tata Kelola Lengkap

Lihat Log Audit

Referensi SDK: Metode Utama

`Client.init()`

`Client.guard(tool, args, method, raise_on_deny, context)`

`Client.close()`

`PolicyDeniedError`

Debugging

Langkah Berikutnya