> ## 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](/environment/initiate_environment).
* 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
```

<Expandable title="command flags">
  <ResponseField name="--artifact / -a" type="string" required>
    Name or display name of the policy artifact to bind. Run `orchestrate controls list-types` to see available values.
  </ResponseField>

  <ResponseField name="--name / -n" type="string" required>
    Internal name for this control binding.
  </ResponseField>

  <ResponseField name="--display-name" type="string">
    Display name for the control. Defaults to `--name` if not provided.
  </ResponseField>

  <ResponseField name="--description / -d" type="string">
    Optional description of what this control does.
  </ResponseField>

  <ResponseField name="--hooks / --hook" type="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`.
  </ResponseField>

  <ResponseField name="--priority / -p" type="integer">
    Execution priority. Lower numbers execute first. Defaults to `100`.
  </ResponseField>

  <ResponseField name="--config" type="string">
    JSON string with artifact-specific configuration options. For example: `'{"action": "redact"}'`.
  </ResponseField>

  <ResponseField name="--agent" type="string">
    Agent name to bind this control to. Specify `--agent` multiple times to bind to several agents.
  </ResponseField>

  <ResponseField name="--tool" type="string">
    Tool name to bind this control to. Specify `--tool` multiple times to bind to several tools.
  </ResponseField>

  <ResponseField name="--model" type="string">
    Model name to bind this control to. Specify `--model` multiple times to bind to several models.
  </ResponseField>
</Expandable>

### 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
```

<Expandable title="YAML field reference">
  <ResponseField name="spec_version" type="enum">
    Schema version. Use `v1`.
  </ResponseField>

  <ResponseField name="kind" type="enum">
    Resource type. Use `control`.
  </ResponseField>

  <ResponseField name="control.artifact_name" type="string" required>
    Name or display name of the policy artifact to bind. Run `orchestrate controls list-types` to see available values.
  </ResponseField>

  <ResponseField name="control.name" type="string" required>
    Internal name for this control binding.
  </ResponseField>

  <ResponseField name="control.display_name" type="string">
    Human-readable display name. Defaults to `name` if not set.
  </ResponseField>

  <ResponseField name="control.description" type="string">
    Optional description.
  </ResponseField>

  <ResponseField name="control.hooks" type="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`.
  </ResponseField>

  <ResponseField name="control.priority" type="integer">
    Execution priority. Defaults to `100`. Lower numbers execute first.
  </ResponseField>

  <ResponseField name="control.config" type="object">
    Artifact-specific configuration. Defaults to `{}`.
  </ResponseField>

  <ResponseField name="control.agent_names" type="string[]">
    List of agent names to bind this control to.
  </ResponseField>

  <ResponseField name="control.tool_names" type="string[]">
    List of tool names to bind this control to.
  </ResponseField>

  <ResponseField name="control.model_names" type="string[]">
    List of model names to bind this control to.
  </ResponseField>
</Expandable>

## 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.
</Warning>

<Expandable title="command flags">
  <ResponseField name="--name / -n" type="string" required>
    Name of the control to update, as shown in `orchestrate controls list`.
  </ResponseField>

  <ResponseField name="--artifact" type="string">
    New policy artifact name or display name.
  </ResponseField>

  <ResponseField name="--new-name" type="string">
    New internal name for the control.
  </ResponseField>

  <ResponseField name="--display-name" type="string">
    New display name.
  </ResponseField>

  <ResponseField name="--description / -d" type="string">
    New description.
  </ResponseField>

  <ResponseField name="--hooks / --hook" type="string">
    New execution hooks. Replaces all existing hooks.
  </ResponseField>

  <ResponseField name="--priority / -p" type="integer">
    New execution priority.
  </ResponseField>

  <ResponseField name="--config" type="string">
    New artifact-specific configuration as a JSON string.
  </ResponseField>

  <ResponseField name="--agent" type="string">
    New agent name(s). Replaces existing agent bindings.
  </ResponseField>

  <ResponseField name="--tool" type="string">
    New tool name(s). Replaces existing tool bindings.
  </ResponseField>

  <ResponseField name="--model" type="string">
    New model name(s). Replaces existing model bindings.
  </ResponseField>
</Expandable>

## 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.