Skip to main content

Escalation Routing Configuration

escalation_routing attaches human-routing hints to provider targets or nested models. When an escalation verdict is emitted, a matching model-level hint takes precedence over the target-level hint. If neither exists, downstream handling is platform-defined.

Supported shape​

Config validation accepts escalation_routing in these locations:

  • providers.targets[].escalation_routing
  • providers.targets[].models[].escalation_routing

Exactly one of team_id or user_id is required.

escalation_routing:
  team_id: team-security
escalation_routing:
  user_id: analyst-on-call

Config validation treats team_id and user_id as strings. It enforces exclusivity, but it does not validate UUID format.

Provider-level routing​

pack:
  name: config-escalation-routing-provider
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: openai-prod
    provider: openai
    model: gpt-5.4-mini
    base_url: https://api.openai.com
    secret_key_ref:
      env: KEEPTRUSTS_OPENAI_API_KEY
    escalation_routing:
      team_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
policies:
  chain:
  - human-oversight
policy:
  human-oversight:
    action: escalate

When an escalation verdict is emitted for this target, the event metadata carries the provider-level routing hint.

Per-model routing​

Use nested model routing when one target serves multiple models. A matched model ID or alias uses its model-level routing hint; a nested model without a hint falls back to the target-level block.

pack:
  name: config-escalation-routing-model
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: openai-production
    provider: openai
    base_url: https://api.openai.com
    secret_key_ref:
      env: KEEPTRUSTS_OPENAI_API_KEY
    escalation_routing:
      team_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    models:
    - model_id: your-primary-openai-model
      aliases:
      - primary
    - model_id: your-secondary-openai-model
      aliases:
      - secondary
      escalation_routing:
        user_id: f0e1d2c3-b4a5-6789-0fed-cba987654321
policies:
  chain:
  - human-oversight
policy:
  human-oversight:
    action: escalate

Replace both model placeholders with identifiers currently available to the provider account.

Requests selecting the secondary model or its secondary alias route escalations to the individual analyst (user_id). The primary model has no model-level override, so it uses the target's team route (team_id).

Operational notes​

  • escalation_routing does not itself trigger escalation; a policy still has to return an escalate verdict.
  • YAML does not define a default queue. If no routing hint is found, downstream handling is platform-defined.
  • Use the Console, control-plane API, kt team list, or kt user list to obtain the correct team and user identifiers.

Next steps​