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 run command to start an existing Python program with Guardian attached. You put the command in front of the command that you normally run, and the program itself doesn't change.
Only this run has Guardian attached, and nothing in your Python environment changes. The program runs as if you launched it with plain python: it still runs as __main__, it keeps its own arguments and exit code, and its standard input, output, and error pass through untouched.
The command runs a program on your own computer. It isn't a way to deploy an agent to a platform such as Databricks. TBC - confirm the supported way to attach Guardian to agents that run on managed platforms, where you control neither the code nor the launch command.
Prerequisites
- You have installed the CLI, in a Guardian preview release. You don't need to set the Collibra environment variables or sign in, because this command sends no request to Collibra. The program itself may still contact Collibra through the SDK.
- The Python interpreter that runs your program is Python 3.12 or newer, and has the Collibra SDK installed, with the extras for the framework that your program uses. For example, for LangChain:
pip install "collibra-sdk[guardian-injection,guardian-langchain]". For the extras of other frameworks, and the framework versions that Guardian supports, go to Guardian SDK settings and supported frameworks. The SDK isn't part of the CLI, and you install it separately. TBC - confirm how customers get access to the package index that hosts the SDK. - Guardian has compiled the enforcement bundle for the AI agent, and the bundle is available to the program, by default as the
bundle.zipfile in the working directory. You can download it with the sync command. If the SDK finds no bundle, Guardian allows every action, so nothing governs the agent. For details, go to Where the SDK finds the enforcement bundle.
The command doesn't download a bundle, and it doesn't run the sync command for you. You can change how Guardian behaves, for example to monitor without applying verdicts, with the SDK settings.
Syntax
collibra ai-gov guardian run [--] <interpreter> <target...>
| Argument | Required | Description |
|---|---|---|
<interpreter>
|
Yes | The Python interpreter to run the program with. It can be a name on the PATH, such as python, or a path, such as .venv/bin/python. |
<target...>
|
Yes | Everything that would follow the interpreter in a plain python command: interpreter options such as -u, the script or the -m module, and the program's own arguments. |
The command has no flags of its own, apart from --help. The CLI only reads what comes before the interpreter, and it accepts and drops a -- written there. Everything from the interpreter onwards reaches your program unread, so your program's own flags never clash with the CLI's.
Before it starts your program, the CLI checks that the interpreter is Python 3.12 or newer and that it can load the SDK. If the check doesn't finish within 30 seconds, or returns no readable answer, the program starts anyway.
Steps
- Open your terminal or command prompt.
- Navigate to the folder from which you normally start your program.
- Write the command that you normally run, and add
collibra ai-gov guardian runin front of it.
For example:- To run a script:
collibra ai-gov guardian run python my-agent.py - To run a module with its own flag:
collibra ai-gov guardian run python -m my_package --flag value - To mark where the CLI's part ends:
collibra ai-gov guardian run -- python my-agent.py --flag value - To use the interpreter of a virtual environment:
collibra ai-gov guardian run .venv/bin/python my-agent.py
- To run a script:
Results and exit status
- If the program finishes successfully, the CLI prints nothing and exits with status 0.
- If the program fails, because it exits with a non-zero status or a signal ends it, the CLI prints nothing, because the program has already written its own error. The CLI exits with the program's status. For a program that a signal ended, this is 128 plus the signal's number, as in a shell.
- If the CLI itself fails, it always prints an error, and it exits with status 3 or 1. For the list of errors, go to Guardian CLI error codes.
Note Because the program's exit status passes through unchanged, the exit status alone doesn't tell you whether the CLI or the program failed. The CLI's own failures always print an error.
- Download the latest enforcement bundle.
- Review the Guardian SDK settings and supported frameworks.
- Learn how to enable Guardian for an agent.
- Go to Guardian CLI error codes if the command returns an error.