> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing controls

> Use the ADK CLI to create, update, and remove policy controls that enforce guardrails and PII filtering on agents, tools, and models.

Controls let you attach policy artifacts — such as PII filters and content guardrails — to agents, tools, and models. When a control is active, the platform applies the policy at the configured execution hooks, for example before an agent runs or after a tool responds.

## Prerequisites

* You must be authenticated. See [Initiating your environment](https://developer.watson-orchestrate.ibm.com/environment/initiate_environment.md).
* Controls require the controls feature to be enabled in your watsonx Orchestrate instance. Contact your administrator if the `orchestrate controls` commands are unavailable.

## Viewing available policy types

Before creating a control, list the policy artifact types available in your instance:

```bash BASH theme={null}
orchestrate controls list-types
```

To see full details for a specific type:

```bash BASH theme={null}
orchestrate controls get-type --name "PII Filter"
```

Use the artifact name shown here as the `--artifact` value when creating a control.

## Creating a control

Bind a policy artifact to one or more agents, tools, or models:

```bash BASH theme={null}
orchestrate controls create \
  --artifact "PII Filter" \
  --name my_pii_control \
  --hook agent_pre_invoke \
  --agent my-agent
```

**command flags**

**--artifact / -a** `string` *required*

Name or display name of the policy artifact to bind. Run `orchestrate controls list-types` to see available values.

**--name / -n** `string` *required*

Internal name for this control binding.

**--display-name** `string`

Display name for the control. Defaults to `--name` if not provided.

**--description / -d** `string`

Optional description of what this control does.

**--hooks / --hook** `string`

One or more execution hooks. Specify `--hook` multiple times to attach to several hooks.

Supported values: `agent_pre_invoke`, `agent_post_invoke`, `tool_pre_invoke`, `tool_post_invoke`, `prompt_pre_fetch`, `prompt_post_fetch`.

**--priority / -p** `integer`

Execution priority. Lower numbers execute first. Defaults to `100`.

**--config** `string`

JSON string with artifact-specific configuration options. For example: `'{"action": "redact"}'`.

**--agent** `string`

Agent name to bind this control to. Specify `--agent` multiple times to bind to several agents.

**--tool** `string`

Tool name to bind this control to. Specify `--tool` multiple times to bind to several tools.

**--model** `string`

Model name to bind this control to. Specify `--model` multiple times to bind to several models.

### Example: Content guardrails on an agent

```bash BASH theme={null}
orchestrate controls create \
  --artifact "Content Guardrails" \
  --name content_safety \
  --description "Blocks harmful content before and after agent execution" \
  --hook agent_pre_invoke \
  --hook agent_post_invoke \
  --priority 100 \
  --config '{"enabled": {"hap": true, "harm": true, "jailbreak": true}, "block_message": "Content blocked by guardrails"}' \
  --agent my-agent
```

## Importing controls from a file

Define one or more controls in a YAML file and import them all at once. This approach is useful for scripting and CI/CD workflows.

```bash BASH theme={null}
orchestrate controls import --file controls.yaml
```

Example YAML file:

```yaml YAML theme={null}
spec_version: v1
kind: control
control:
  artifact_name: Content Guardrails
  name: content_guardrails_example
  display_name: Content Guardrails Example
  description: Enforces content safety on agent invocations.
  hooks:
    - agent_pre_invoke
    - agent_post_invoke
  priority: 100
  config:
    enabled:
      hap: true
      harm: true
      violence: true
      jailbreak: true
      social_bias: true
      sexual_content: true
    block_message: Content blocked by guardrails controls
  agent_names:
    - my-agent
  # tool_names:
  #   - my-tool
  # model_names:
  #   - my-model
```

**YAML field reference**

**spec\_version** `enum`

Schema version. Use `v1`.

**kind** `enum`

Resource type. Use `control`.

**control.artifact\_name** `string` *required*

Name or display name of the policy artifact to bind. Run `orchestrate controls list-types` to see available values.

**control.name** `string` *required*

Internal name for this control binding.

**control.display\_name** `string`

Human-readable display name. Defaults to `name` if not set.

**control.description** `string`

Optional description.

**control.hooks** `string[]`

List of execution hooks. Supported values: `agent_pre_invoke`, `agent_post_invoke`, `tool_pre_invoke`, `tool_post_invoke`, `prompt_pre_fetch`, `prompt_post_fetch`.

**control.priority** `integer`

Execution priority. Defaults to `100`. Lower numbers execute first.

**control.config** `object`

Artifact-specific configuration. Defaults to `{}`.

**control.agent\_names** `string[]`

List of agent names to bind this control to.

**control.tool\_names** `string[]`

List of tool names to bind this control to.

**control.model\_names** `string[]`

List of model names to bind this control to.

## Listing controls

List all controls in your active environment:

```bash BASH theme={null}
orchestrate controls list
```

Filter by a specific asset:

```bash BASH theme={null}
orchestrate controls list --agent my-agent
orchestrate controls list --tool my-tool
orchestrate controls list --artifact "PII Filter"
```

Use `--verbose` to show full JSON details:

```bash BASH theme={null}
orchestrate controls list --verbose
```

## Getting control details

```bash BASH theme={null}
orchestrate controls get-details --name my_pii_control
```

## Updating a control

Update specific fields of an existing control. Only the fields you provide are changed:

```bash BASH theme={null}
orchestrate controls update \
  --name my_pii_control \
  --priority 50 \
  --hook agent_post_invoke
```

> [!WARNING]
>
> When you update `--agent`, `--tool`, or `--model` values, the provided list **replaces** the existing bindings for that asset type entirely. To keep existing bindings, include them alongside the new ones.

**command flags**

**--name / -n** `string` *required*

Name of the control to update, as shown in `orchestrate controls list`.

**--artifact** `string`

New policy artifact name or display name.

**--new-name** `string`

New internal name for the control.

**--display-name** `string`

New display name.

**--description / -d** `string`

New description.

**--hooks / --hook** `string`

New execution hooks. Replaces all existing hooks.

**--priority / -p** `integer`

New execution priority.

**--config** `string`

New artifact-specific configuration as a JSON string.

**--agent** `string`

New agent name(s). Replaces existing agent bindings.

**--tool** `string`

New tool name(s). Replaces existing tool bindings.

**--model** `string`

New model name(s). Replaces existing model bindings.

## Exporting a control

Export a control to a YAML file to version it or re-import it in another environment:

```bash BASH theme={null}
orchestrate controls export --name my_pii_control --output my_pii_control.yaml
```

## Removing a control

```bash BASH theme={null}
orchestrate controls remove --name my_pii_control
```

This removes the control and all of its associated bindings.
