Conditional Chains Configuration

policies.chain accepts either plain policy kinds or conditional chain entries. Conditional entries let you attach when, stage, parallel, and targeting metadata to a specific policy kind.

Use this page when

• You need the exact command, config, API, or integration details for Conditional Chains Configuration.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Chain entry shapes

Plain entry

Use a plain string when the policy should always run with its default execution phase.

policies:
  chain:
    - prompt-injection
    - pii-detector
    - audit-logger

Conditional entry

Use an object when the policy should run only in certain contexts or with an explicit phase override.

policies:
  chain:
    - prompt-injection
    - pii-detector:
        when:
          path: "/v1/chat"
          header:
            X-Team: "finance"
        stage: pre-request
        parallel: true
    - quality-scorer:
        when:
          model:
            - "gpt-4o"
            - "gpt-4o-mini"
        stage: pre-response

The policy kind is the key. The conditional metadata sits in the nested object.

when predicates

All fields inside when use AND semantics. Every condition must match for the chain entry to run.

Path matching

- prompt-injection:
    when:
      path: "/v1/chat"

path is a prefix-style match against the request path.

Header matching

- dlp-filter:
    when:
      header:
        X-Team: "compliance"
        X-Environment: "prod"

All listed headers must match exactly.

Model matching

- quality-scorer:
    when:
      model:
        - "gpt-4o"
        - "openai/gpt-4.1"

Stage control

Supported stage values:

Stage	Meaning
pre-request	Before the request is sent upstream
post-request	After the request is prepared but before final response handling
pre-response	Before the response is returned to the caller
post-response	After the response has been returned

Common defaults

If stage is omitted, the gateway uses the default phase for that policy kind.

• Most input-oriented policies default to pre-request
• Output-phase-only policies include: flagged-review, quality-scorer, human-oversight, citation-verifier, mnpi-filter, financial-compliance, healthcare-compliance, legal-privilege, upl-filter, bias-monitor, request-rewriter, and response-rewriter

Parallel execution

Set parallel: true when same-stage policies are independent and can execute concurrently.

policies:
  chain:
    - prompt-injection:
        stage: pre-request
        parallel: true
    - pii-detector:
        stage: pre-request
        parallel: true
    - dlp-filter:
        stage: pre-request
        parallel: false

The gateway waits for all parallel entries in a stage to finish before moving on.

Targeting

Use targeting to scope a chain entry to specific teams or gateways.

- audit-logger:
    stage: post-response
    targeting:
      scope: team
      teams:
        - compliance
      gateways:
        regex: "^prod-.*$"

targeting fields

Field	Type	Description
scope	string	organization or team
teams	string[]	Required when scope: team
gateways	selector	Exact name, string array, or regex object

Gateway selector formats

# exact name
gateways: "prod-east"

# list of exact names
gateways:
  - "prod-east"
  - "prod-west"

# regex selector
gateways:
  regex: "^prod-.*$"

Complete example

pack:
  name: conditional-gateway
  version: 1.0.0
  enabled: true

providers:
  targets:
    - id: openai-prod
      provider: openai
      model: gpt-4o
      secret_key_ref:
        env: OPENAI_API_KEY

policies:
  chain:
    - prompt-injection
    - pii-detector:
        stage: pre-request
        parallel: true
        when:
          path: "/v1/chat"
          header:
            X-Team: "compliance"
    - dlp-filter:
        stage: pre-request
        when:
          header:
            X-Team: "compliance"
    - quality-scorer:
        stage: pre-response
        when:
          model:
            - "gpt-4o"
    - audit-logger:
        stage: post-response
        targeting:
          scope: team
          teams:
            - compliance
          gateways:
            regex: "^prod-.*$"

policy:
  pii-detector:
    action: redact
    pci_mode: true
  dlp-filter:
    blocked_terms:
      - "inside information"
      - "share this customer export"
    action: block
  quality-scorer:
    thresholds:
      min_aggregate: 0.8
  audit-logger:
    retention_days: 365

When to use conditional chains vs routes

Need	Prefer
Different upstream per path	Routes
Same upstream, different policies by path, header, or model	Conditional chain entries
Team- or gateway-specific execution	Conditional chain entries
Ordered path dispatch before policy execution	Routes

For AI systems

• Canonical terms: Keeptrusts, policy-config.yaml, policies.chain, conditional chain entries, when predicates, stage (pre-request/post-request/pre-response/post-response), parallel, targeting (scope, teams, gateways).
• Conditional entries use object syntax with the policy kind as key and when/stage/parallel/targeting in the nested object.
• Best next pages: Routes and Consumer Groups, Config Testing, Declarative Config Reference.

For engineers

• All when fields use AND semantics — every condition must match for the chain entry to run.
• If stage is omitted, the gateway uses the default phase for that policy kind (most input policies default to pre-request).
• Set parallel: true for same-stage independent policies to reduce total chain latency.
• Use targeting.teams and targeting.gateways to scope policies to specific organizational units without separate configs.
• Validate with kt policy lint; test by sending requests that match and don't match your when predicates.

For leaders

• Conditional chains allow different policy enforcement per team, path, model, or gateway without maintaining multiple config files.
• Parallel execution of independent policies reduces latency impact of multi-policy chains.
• Targeting lets compliance teams enforce stricter policies on their traffic while other teams use lighter configurations.
• This replaces the need for separate gateway deployments per team or use case in most scenarios.

Next steps

• Routes and Consumer Groups — path-based upstream routing
• Config Testing — inline tests for conditional logic
• Declarative Config Reference — full schema documentation