Important Guardian Agents are available in private preview. The command in this topic is only included in the CLI's Guardian preview releases, and it doesn't appear in the CLI's help. Details are based on an early build and are subject to change before general availability.
Use the collibra ai-gov guardian sync command to synchronize the enforcement bundle on your computer with the latest version that Guardian compiled for an AI agent. The enforcement bundle contains the compiled rules, built from the AI agent's Agent Contracts, that Guardian enforces at runtime.
The command only downloads the bundle when needed. If the bundle on your computer is already the latest, nothing is downloaded.
Prerequisites
- You have installed and set up the CLI, in a Guardian preview release, and you're signed in or have set the environment variables for your authentication method.
- Guardian has compiled an enforcement bundle for the AI agent. If it hasn't, the command returns an error. To compile the latest rules, click Apply latest rules on the Contract tab of the AI Agent asset page.
- Your credentials give access to the Collibra environment. The command uses the same credentials as other CLI commands, and returns an access denied error if your token doesn't cover the environment. TBC - the API documents the scope aigovernance.guardian.enforcement-read for downloading a bundle, but it isn't enforced yet, and the CLI doesn't request it. Confirm the permission or scope that is required when it ships.
- You know the UUID of the AI agent, which is the ID of the AI Agent asset. Guardian only knows AI agents that have been fingerprinted, and it returns an error for any other ID. TBC - confirm where users find the UUID (for example, in the URL of the AI Agent asset page).
Syntax
collibra ai-gov guardian sync --agent-id <UUID> [--output <PATH>]
| Flag | Required | Default | Description |
|---|---|---|---|
--agent-id
|
Yes | None | The UUID of the AI agent to download the enforcement bundle for. |
--output
|
No | bundle.zip
|
The path to write the downloaded bundle ZIP file to. |
Note The command always writes a manifest file, bundle.manifest.yaml, in the same folder as the ZIP file. The manifest records which AI agent, version, and content the bundle has, so that the next run can tell whether the bundle is up to date.
Steps
- Open your terminal or command prompt.
- Run the following command, and replace the placeholder with your AI agent's UUID:
collibra ai-gov guardian sync --agent-id <UUID>
To save the bundle somewhere other than the current folder, add the--outputflag, for example--output ./bundles/agent.zip.
Results
The result depends on whether the bundle on your computer is up to date.
- The bundle is already up to date. The ZIP file and the manifest file exist, and the manifest's AI agent, version, and content hash all match what Guardian reports. The CLI doesn't download anything, and shows
Enforcement bundle is already up to date (version 3)., with your version number. - The bundle is downloaded. The CLI downloads a new bundle, checks its integrity, and writes the ZIP file and the manifest file. It shows the version and size, followed by the paths of both files:
Downloading enforcement bundle version 3 (1048576 bytes)...Enforcement bundle downloaded and verified.
The CLI downloads a new bundle in any of the following cases:
- The ZIP file doesn't exist, even if the manifest matches.
- The manifest file doesn't exist.
- The manifest belongs to a different AI agent.
- The manifest's version is older than the latest version.
- The manifest's content hash differs from the latest one.
The CLI downloads the bundle through a signed link, and verifies its SHA-256 hash before it writes the file. If the link has expired, run the command again.
Note The default output file, bundle.zip, is the file that the SDK looks for by default in its working directory. To use the bundle with the run command, run both commands from the same folder, or set the policy_bundle SDK setting. The sync command doesn't start your program, and the run command doesn't download a bundle.
For the errors that the command can return, go to Guardian CLI error codes.
- Run a Python program with Guardian attached.
- Learn how to enable Guardian for an agent.
- Go to Guardian CLI error codes if the command returns an error.