Managing controls

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

orchestrate controls list-types

To see full details for a specific type:

BASH

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

orchestrate controls create \
  --artifact "PII Filter" \
  --name my_pii_control \
  --hook agent_pre_invoke \
  --agent my-agent

Show command flags

string

required

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

string

required

Internal name for this control binding.

string

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

string

Optional description of what this control does.

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.

integer

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

string

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

string

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

string

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

string

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

Example: Content guardrails on an agent

BASH

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

orchestrate controls import --file controls.yaml

Example YAML file:

YAML

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

Show YAML field reference

enum

Schema version. Use v1.

enum

Resource type. Use control.

string

required

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

string

required

Internal name for this control binding.

string

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

string

Optional description.

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.

integer

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

object

Artifact-specific configuration. Defaults to {}.

string[]

List of agent names to bind this control to.

string[]

List of tool names to bind this control to.

string[]

List of model names to bind this control to.

Listing controls

List all controls in your active environment:

BASH

orchestrate controls list

Filter by a specific asset:

BASH

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

orchestrate controls list --verbose

Getting control details

BASH

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

orchestrate controls update \
  --name my_pii_control \
  --priority 50 \
  --hook agent_post_invoke

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.

Show command flags

string

required

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

string

New policy artifact name or display name.

string

New internal name for the control.

string

New display name.

string

New description.

string

New execution hooks. Replaces all existing hooks.

integer

New execution priority.

string

New artifact-specific configuration as a JSON string.

string

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

string

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

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

orchestrate controls export --name my_pii_control --output my_pii_control.yaml

Removing a control

BASH

orchestrate controls remove --name my_pii_control

This removes the control and all of its associated bindings.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Prerequisites

Viewing available policy types

Creating a control

Example: Content guardrails on an agent

Importing controls from a file

Listing controls

Getting control details

Updating a control

Exporting a control

Removing a control

​Prerequisites

​Viewing available policy types

​Creating a control

​Example: Content guardrails on an agent

​Importing controls from a file

​Listing controls

​Getting control details

​Updating a control

​Exporting a control

​Removing a control

Prerequisites

Viewing available policy types

Creating a control

Example: Content guardrails on an agent

Importing controls from a file

Listing controls

Getting control details

Updating a control

Exporting a control

Removing a control