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

SDK Python

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

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

The Control Zero Python SDK provides deterministic policy enforcement for AI agents running in Python environments. A deny stops the guarded call before it executes. Hosted policies arrive as signed bundles that are verified before use, and the SDK fails closed by default when it cannot establish coverage.

Pilih titik penerapan yang sesuai

Gunakan gateway proxy untuk aplikasi yang tidak dapat Anda ubah dan hook pengodean untuk alat AI developer. Gunakan SDK ini jika Anda mengendalikan kode aplikasi Python.

Instalasi

pip install controlzero

Persyaratan:

Python 3.9 atau yang lebih baru
Tidak ada dependensi sistem tambahan

Mulai Cepat

Pilih mode deployment Anda:

Hosted
Hybrid
Local

Hosted Kebijakan diambil dari dasbor.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Audit in cloud.

Direkomendasikan untuk sebagian besar tim.

from controlzero import Client

# SDK fetches your signed policy bundle on first call.
# Manages audit automatically. No local config needed.
client = Client(api_key="cz_live_your_api_key_here")
# Or use env var: export CONTROLZERO_API_KEY="cz_live_..."

Instal: pip install controlzero (dependensi mode cloud sudah disertakan dalam instalasi dasar sejak 1.4.3).

Hybrid Kunci API ditambah file kebijakan lokal.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

When you pass policy or policy_file explicitly to Client() alongside an api_key, your local policy governs enforcement and the hosted/dashboard bundle is IGNORED for that instance -- audit still ships to your dashboard.

SDK mencetak satu kali peringatan agar pilihan ini terlihat (berikan strict_hosted=True untuk memunculkan HybridModeError sebagai gantinya). CONTROLZERO_LOCAL_OVERRIDE tidak berlaku pada kasus argumen eksplisit ini; variabel tersebut hanya memengaruhi penemuan otomatis (api_key diatur dan Anda TIDAK memberikan policy/policy_file, tetapi sebuah file lokal ditemukan melalui CONTROLZERO_POLICY_FILE atau controlzero.yaml/.yml/.json di direktori kerja), di mana bundel hosted menang secara default dan CONTROLZERO_LOCAL_OVERRIDE=1 beralih ke file lokal yang ditemukan.

from controlzero import Client

# Your local file governs enforcement; the hosted bundle is ignored.
client = Client(
    api_key="cz_live_your_api_key_here",
    policy_file="controlzero.yaml",
)

# The local file already governs enforcement; the API key only routes audit to the dashboard.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Your local policy governs enforcement; the API key only routes audit to the dashboard.

SDK akan mencetak satu kali peringatan yang menyatakan bahwa kebijakan dasbor diabaikan untuk instance ini (atau memunculkan HybridModeError jika Anda mengatur strict_hosted=True).

Local Tanpa kunci API.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

No network calls.

Sepenuhnya offline. Kompatibel dengan air-gap.

from controlzero import Client

# Inline policy -- no file needed
client = Client(policy={
    "rules": [
        {"allow": "database:query",   "reason": "Reads are permitted"},
        {"deny":  "database:execute", "reason": "Writes are blocked"},
    ]
})

# Or from a file
client = Client(policy_file="controlzero.yaml")

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Every decision and its event-level coverage is written to ./controlzero.log, so “did not run” remains distinguishable from “ran and found nothing.”

Konfigurasi

Hosted Mode Hosted (Direkomendasikan)

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Pass only your project API key. The SDK pulls the signed policy bundle from the dashboard at first call, verifies its signature, decrypts locally, and enforces every call against the dashboard policy. Audit entries ship to the remote trail automatically.

from controlzero import Client

client = Client(api_key="cz_live_your_api_key_here")

Local Dengan File Kebijakan Lokal

from controlzero import Client

client = Client(policy_file="controlzero.yaml")

Hybrid Mode Hybrid (Kunci API + Kebijakan Lokal)

from controlzero import Client

# Explicit policy_file + api_key: the local file governs enforcement,
# the hosted bundle is IGNORED, audit still ships remotely.
client = Client(api_key="cz_live_your_api_key_here", policy_file="controlzero.yaml")

Kebijakan Inline

from controlzero import Client

client = Client(policy={
    "rules": [
        {"allow": "database:query", "reason": "Reads are permitted"},
        {"deny": "database:*", "reason": "All other database operations are blocked"},
    ]
})

Nama aksi lama dan nama kanonis sama-sama berfungsi

database:query, database:execute, dan database:delete adalah nama aksi lama yang cocok dengan panggilan yang sama seperti kelas kanonis database:read, database:write, dan database:admin. Kebijakan baru sebaiknya memakai nama kanonis; aturan yang sudah ada dengan nama lama tetap berfungsi tanpa perubahan. Lihat Resep database hanya-baca untuk pemetaan kelas semantik SQL.

Pencocokan resource dengan wildcard

Aturan yang mencantumkan resources: ["*"] cocok dengan setiap panggilan, terlepas dari apakah pemanggil memberikan context.resource. Gunakan ini ketika sebuah aturan harus berlaku secara universal dan Anda tidak memiliki (atau tidak ingin memberikan) resource per panggilan:

# Policy rule with universal resource matching
{"effect": "allow", "actions": ["database:read"], "resources": ["*"]}

# This call matches even though context.resource is not set:
cz.guard("database", method="query", args={"sql": "SELECT 1"})

Pola resource non-wildcard (misalnya resources: ["table/orders"]) tetap mengharuskan pemanggil memberikan context.resource yang cocok agar aturan berlaku. Dengan begitu, aturan yang sempit tetap sempit.

Variabel Lingkungan

Anda dapat memberikan kunci API secara eksplisit atau mengaturnya melalui variabel lingkungan CONTROLZERO_API_KEY. Nama agen dapat diatur melalui CZ_AGENT_NAME.

export CONTROLZERO_API_KEY="cz_live_your_api_key_here"
export CZ_AGENT_NAME="my-analyst-agent"

from controlzero import Client

client = Client()  # reads CONTROLZERO_API_KEY from environment

Opsi Konfigurasi

Parameter	Tipe	Default	Deskripsi
`api_key`	`str`	`CONTROLZERO_API_KEY` env	Project API key. Enables hosted mode: SDK auto-pulls the signed policy bundle from the dashboard and ships audit to the remote trail.
`policy`	`dict`	`None`	Dict kebijakan inline berisi aturan.
`policy_file`	`str`	`None`	Path ke file kebijakan YAML atau JSON.
`strict_hosted`	`bool`	`False`	Memunculkan `HybridModeError` ketika `api_key` diberikan bersama `policy`/`policy_file` eksplisit, alih-alih memakai kebijakan lokal dengan satu kali peringatan. Berguna di CI untuk menangkap override lokal yang tidak disengaja.
`refresh_interval_seconds`	`int`	`60`	Mode hosted: seberapa sering memeriksa dasbor untuk bundel kebijakan terbaru. Berikan `None` untuk menonaktifkan penyegaran otomatis. Berikan `0` untuk menyegarkan pada setiap panggilan `guard()` (hanya untuk pengujian).
`log_path`	`str`	`"./controlzero.log"`	Path file log audit lokal.
`log_rotation`	`str`	`"daily"`	Interval rotasi log audit.
`log_retention`	`str`	`"30 days"`	How long to keep rotated logs.
`log_compression`	`str`	`None`	Kompres log hasil rotasi (mis. `"gz"`).
`log_format`	`str`	`"json"`	Format log audit.

Penyegaran kebijakan (mode hosted)

Ketika Anda memperbarui kebijakan di dasbor, proses SDK yang berjalan lama otomatis mengambil perubahan tersebut dalam interval penyegaran (default: 60 detik). SDK mengirim permintaan bersyarat sehingga bundel yang tidak berubah hanya membutuhkan satu roundtrip kecil.

Tiga pengaturan:

refresh_interval_seconds=60 (default): periksa setiap menit.
refresh_interval_seconds=None: nonaktifkan pemeriksaan latar belakang. Gabungkan dengan client.refresh() untuk kontrol manual penuh.
client.refresh(): paksa pemuatan ulang segera. Mengembalikan True jika bundel benar-benar berubah, False jika dasbor tidak memiliki pembaruan.

from controlzero import Client

# Long-lived agent, picks up dashboard changes within 60s automatically.
client = Client(api_key="cz_live_your_api_key_here")

# Or: force an immediate reload after a known dashboard change.
changed = client.refresh()
if changed:
    print(f"Policy updated at {client.last_refreshed_at.isoformat()}")

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Network errors during a background refresh are logged at WARNING level and do not raise; the last-known-good bundle keeps working until the next successful pull.

Penggunaan Dasar

Mengevaluasi Pemanggilan Alat

Metode utamanya adalah guard(), yang mengevaluasi kebijakan yang aktif:

from controlzero import Client, PolicyDeniedError

client = Client(policy_file="controlzero.yaml")

decision = client.guard(
    "database",
    method="query",
    args={"sql": "SELECT * FROM orders"},
)
print(decision.effect)     # "allow" or "deny"
print(decision.reason)     # human-readable reason
print(decision.policy_id)  # matching policy ID

Menangani Aksi yang Ditolak

Ketika kebijakan menolak aksi, periksa efek keputusan atau tangkap PolicyDeniedError:

from controlzero import Client, PolicyDeniedError

client = Client(policy_file="controlzero.yaml")

decision = client.guard(
    "filesystem",
    method="write_file",
    args={"path": "/data/output.csv", "content": "..."},
)
if decision.effect == "deny":
    print(f"Blocked: {decision.reason}")
    print(f"Policy: {decision.policy_id}")

Context Manager

Client mengimplementasikan protokol context manager. Menggunakan with akan memanggil close() saat keluar:

from controlzero import Client

with Client(policy_file="controlzero.yaml") as client:
    decision = client.guard("github", method="list_issues", args={"repo": "acme/app"})

Referensi API

`Client`

Kelas klien sinkron utama.

`init(api_key=None, policy=None, policy_file=None, strict_hosted=False, log_path="./controlzero.log", log_rotation="daily", log_retention="30 days", log_compression=None, log_format="json")`

Membuat klien Control Zero baru.

Memunculkan ValueError jika policy dan policy_file sama-sama diberikan.

`guard(tool, args=None, method="*", raise_on_deny=False, context=None) -> PolicyDecision`

Mengevaluasi pemanggilan alat terhadap kebijakan yang dimuat.

Parameter:

Nama	Tipe	Wajib	Default	Deskripsi
`tool`	`str`	Ya	-	Nama alat. Digabungkan dengan `method` untuk membentuk aksi.
`args`	`dict`	Tidak	`None`	Argumen untuk pemindaian DLP dan evaluasi bersyarat.
`method`	`str`	Tidak	`"*"`	Nama metode. Aksi yang dievaluasi adalah `"{tool}:{method}"`.
`raise_on_deny`	`bool`	Tidak	`False`	Jika `True`, memunculkan `PolicyDeniedError` pada keputusan penolakan.
`context`	`dict`	Tidak	`None`	Konteks opsional dengan kunci `resource` dan `tags` untuk pencocokan.

Mengembalikan: PolicyDecision dengan effect, reason, policy_id, dan dlp_findings.

`close() -> None`

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Flushes buffered audit logs, wipes secrets from memory, and closes the HTTP connection.

`PolicyDecision`

Dikembalikan oleh guard().

Atribut	Tipe	Deskripsi
`effect`	`str`	`"allow"` atau `"deny"`.
`policy_id`	`str or None`	Kebijakan yang cocok, jika ada.
`reason`	`str`	Penjelasan yang dapat dibaca manusia.
`dlp_findings`	`list`	Daftar kecocokan DLP yang ditemukan pada argumen.

`PolicyDeniedError`

Dapat dimunculkan ketika kebijakan menolak aksi.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

The tool is never invoked.

Atribut	Tipe	Deskripsi
`e.decision`	`PolicyDecision`	Objek keputusan lengkap.
`e.decision.effect`	`str`	Selalu `"deny"`.
`e.decision.reason`	`str`	Penjelasan keputusan yang dapat dibaca manusia.
`e.decision.policy_id`	`str or None`	ID kebijakan yang cocok, jika ada.

`BundleSignatureError`

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Raised when a policy bundle fails cryptographic signature verification. The SDK will not load a tampered bundle.

Penanganan Kesalahan

from controlzero import Client, PolicyDeniedError

client = Client(policy_file="controlzero.yaml")

decision = client.guard("database", method="query", args={"sql": "SELECT 1"})
if decision.effect == "deny":
    print(f"Policy denied: {decision.reason}")

client.close()

Penggunaan dengan MCP

Control Zero dirancang untuk mengendalikan pemanggilan alat MCP. Berikan nama server MCP dan nama alat langsung ke guard():

from controlzero import Client

with Client(api_key="cz_live_your_api_key_here") as client:
    decision = client.guard(
        "filesystem",          # MCP server name
        method="read_file",    # MCP tool name
        args={"path": "/data/report.pdf"},
    )
    if decision.effect == "deny":
        print(f"MCP tool blocked: {decision.reason}")

Untuk panduan rinci tentang pola tata kelola MCP, lihat Mengendalikan pemanggilan alat MCP.

Wrapper Penyedia LLM

SDK Python menyertakan fungsi wrapper mandiri yang menambahkan tata kelola ke klien penyedia LLM yang populer. Setiap wrapper mencegat panggilan, mengevaluasi kebijakan, dan mencatat keputusan tanpa mengubah permukaan API asli penyedia.

OpenAI

from controlzero import Client
from controlzero.integrations.openai import wrap_openai
import openai

client = Client(api_key="cz_live_your_api_key_here")
wrapped = wrap_openai(openai.OpenAI(), client)

response = wrapped.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Hello"}],
)

Google AI (Gemini)

from controlzero import Client
from controlzero.integrations.google import wrap_google
from google import genai

client = Client(api_key="cz_live_your_api_key_here")
google_client = genai.Client(api_key="your-google-ai-key")
wrapped_model = wrap_google(google_client.models, client)

response = wrapped_model.generate_content(
    model="gemini-2.0-flash",
    contents="Summarize the quarterly report",
)
print(response.text)

Anthropic

from controlzero import Client
from controlzero.integrations.anthropic import wrap_anthropic
import anthropic

client = Client(api_key="cz_live_your_api_key_here")
wrapped = wrap_anthropic(anthropic.Anthropic(), client)

message = wrapped.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

Wrapper yang Tersedia

Fungsi	Penyedia	Path Impor
`wrap_openai()`	OpenAI	`controlzero.integrations.openai`
`wrap_anthropic()`	Anthropic (Claude)	`controlzero.integrations.anthropic`
`wrap_google()`	Google AI (Gemini)	`controlzero.integrations.google`

Semua wrapper menerapkan pemeriksaan pra-eksekusi (pemblokiran model, estimasi biaya, deteksi PII) dan mencatat permintaan ke jejak audit. Jika kebijakan menolak permintaan, PolicyDeniedError dimunculkan sebelum panggilan mencapai penyedia.

Instalasi​

Mulai Cepat​

Konfigurasi​

Hosted Mode Hosted (Direkomendasikan)​

Local Dengan File Kebijakan Lokal​

Hybrid Mode Hybrid (Kunci API + Kebijakan Lokal)​

Kebijakan Inline​

Pencocokan resource dengan wildcard​

Variabel Lingkungan​

Opsi Konfigurasi​

Penyegaran kebijakan (mode hosted)​

Penggunaan Dasar​

Mengevaluasi Pemanggilan Alat​

Menangani Aksi yang Ditolak​

Context Manager​

Referensi API​

Client​

__init__(api_key=None, policy=None, policy_file=None, strict_hosted=False, log_path="./controlzero.log", log_rotation="daily", log_retention="30 days", log_compression=None, log_format="json")​

guard(tool, args=None, method="*", raise_on_deny=False, context=None) -> PolicyDecision​

close() -> None​

PolicyDecision​

PolicyDeniedError​

BundleSignatureError​

Penanganan Kesalahan​

Penggunaan dengan MCP​

Wrapper Penyedia LLM​

OpenAI​

Google AI (Gemini)​

Anthropic​

Wrapper yang Tersedia​

Instalasi

Mulai Cepat

Konfigurasi

Hosted Mode Hosted (Direkomendasikan)

Local Dengan File Kebijakan Lokal

Hybrid Mode Hybrid (Kunci API + Kebijakan Lokal)

Kebijakan Inline

Pencocokan resource dengan wildcard

Variabel Lingkungan

Opsi Konfigurasi

Penyegaran kebijakan (mode hosted)

Penggunaan Dasar

Mengevaluasi Pemanggilan Alat

Menangani Aksi yang Ditolak

Context Manager

Referensi API

`Client`

`init(api_key=None, policy=None, policy_file=None, strict_hosted=False, log_path="./controlzero.log", log_rotation="daily", log_retention="30 days", log_compression=None, log_format="json")`

`guard(tool, args=None, method="*", raise_on_deny=False, context=None) -> PolicyDecision`

`close() -> None`

`PolicyDecision`

`PolicyDeniedError`

`BundleSignatureError`

Penanganan Kesalahan

Penggunaan dengan MCP

Wrapper Penyedia LLM

OpenAI

Google AI (Gemini)

Anthropic

Wrapper yang Tersedia