プロジェクト
プロジェクトは、Control Zero における最上位の組織単位です。特定の AI エージェント群に対するポリシー、API キー、監査ログをまとめます。
プロジェクトとは
プロジェクトは、ガバナンスの論理的な境界を表します。通常は、環境ごと（例: production、staging）またはアプリケーションごと（例: customer-support-agent、data-pipeline-agent）に1つのプロジェクトを作成します。
各プロジェクトには、次のものがあります。
- 一意のプロジェクト ID（例:
proj_abc123）。 - SDK の認証に使う1つ以上の API キー。
- このプロジェクト内のエージェントに対するガバナンスルールを定義するポリシーのセット。
- このプロジェクトに接続された SDK が行ったすべてのポリシー判定の監査ログ。
プロジェクトを作成する
プロジェクトは、Control Zero のダッシュボードまたは API から作成できます。
ダッシュボード
- サイドバーの Projects に移動します。
- Create Project をクリックします。
- 名前と、任意で説明を入力します。
- Create をクリックします。
API
curl -X POST https://api.controlzero.ai/v1/projects \
-H "Authorization: Bearer YOUR_ORG_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "production-agents",
"description": "Production AI agent governance"
}'
レスポンス:
{
"id": "proj_abc123",
"name": "production-agents",
"description": "Production AI agent governance",
"created_at": "2026-03-01T00:00:00Z"
}
API キー
各プロジェクトには、SDK が認証してポリシーバンドルをダウンロードするために使う API キーがあります。
キーの種類
| 種類 | プレフィックス | 用途 |
|---|---|---|
| Live | cz_live_ | 本番環境での使用。ポリシーが完全に適用され、監査ログが記録されます。 |
| Test | cz_test_ | 開発とテスト。ポリシーは評価されますが、操作がブロックされることはありません（ログのみのモード）。 |
キーを管理する
API キーの作成、ローテーション、失効は、プロジェクトの設定ページから行えます。
- 作成: プロジェクトの新しいキーを生成します。複数のキーを同時に有効にできます。
- ローテーション: 新しいキーを生成し、古いキーに有効期限を設定します。これにより、ダウンタイムなしでキーをローテーションできます。
- 失効: キーを直ちに無効にします。失効したキーを使っている SDK は、次回のポリシー更新時にアクセスできなくなります。
英語の原文 -- 翻訳は技術レビュー待ちです
API keys are shown only once at creation time. Store them securely. If you lose a key, you must create a new one.
SDK でキーを使う
SDK を初期化するときに API キーを渡します。
# Python
from controlzero import Client
client = Client(api_key="cz_live_your_api_key_here")
// Go
client, err := controlzero.New(
controlzero.WithAPIKey("cz_live_your_api_key_here"),
)
API キーは環境変数でも設定できます。
export CONTROLZERO_API_KEY="cz_live_your_api_key_here"
プロジェクトは API キーによって決まります。
英語の原文 -- 翻訳は技術レビュー待ちです
Each key belongs to exactly one project, and
the project identity arrives inside the signed policy bundle — there is no
CONTROLZERO_PROJECT_ID environment variable.
controlzero whoami を実行すると、環境内のキーがどのプロジェクトと組織に対応しているかを確認できます。
ポリシーの割り当て
ポリシーはプロジェクトのレベルで割り当てられます。プロジェクト内でポリシーを作成または変更すると、そのプロジェクト向けに次にコンパイルされるポリシーバンドルに自動的に含まれます。
有効なポリシー
ポリシーバンドルに含まれるのは、公開済みのポリシーだけです。ドラフトのポリシーは適用されません。
1つのプロジェクトに、複数の有効なポリシーを持たせることがで きます。すべての有効なポリシーが、あらゆるアクションチェックで評価されます。すべてのポリシーのルールは結合され、標準の評価順序を使ってまとめて評価されます。
ポリシーのバージョン管理
ポリシーを公開するたびに、新しいバージョンが作成されます。次のことができます。
- すべてのポリシーバージョンの履歴を表示する。
- 必要に応じて以前のバージョンにロールバックする。
- バージョンを比較して、何が変わったかを確認する。
プロジェクトの設定
| 設定 | 説明 | デフォルト |
|---|---|---|
| デフォルトのエフェクト | アクションに一致するポリシールールがない場合に適用されるエフェクトです。 | deny |
| バンドル更新間隔 | SDK が新しいポリシーバンドルをポーリングする頻度（秒）です。SDK ごとにデフォルトが異なります。Python は 60、Node は 300 です。 | 60 |
| ログのみのモード | 有効にすると、ポリシーは評価されてログに記録されますが、操作がブロックされることはありません。 | false |
英語の原文 -- 翻訳は技術レビュー待ちです
Audit log retention is not a project setting. It is configured per organization, defaults to 30 days today, and an owner can set it between 1 and 2555 days; see Account Management.
プロジェクトの構成方法
プロジェクトを構成する一般的なパターンを紹介します。
環境別: production、staging、development それぞれに別のプロジェクトを作成します。本番には厳格なポリシーを適用しながら、開発はより許容的にしておけます。
アプリケーション別: 個別のエージェントアプリケーションごとにプロジェクトを作成します。
英語の原文 -- 翻訳は技術レビュー待ちです
This isolates policies and audit logs per application.
チーム別: チームごとにプロジェクトを作成すると、組織全体の監督を維持しながら、ポリシーの管理を委任できます。
これらのパターンは組み合わせられます。
英語の原文 -- 翻訳は技術レビュー待ちです
For example, customer-support-production and customer-support-staging give you both application and environment isolation.