Skip to main content

Escalation route configuration

escalation_routing adds human route data to provider targets or nested models. If the runtime emits an escalation verdict, it uses the applicable route data.

Model route data overrides target route data. If the two values are missing, the platform controls downstream handling.

Accepted structure​

Configuration validation accepts escalation_routing in these locations:

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

Set exactly one of team_id or user_id.

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

Configuration validation reads team_id and user_id as strings. It lets you use only one field. It does not validate UUID format.

Provider route​

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

When the runtime emits an escalation verdict for this target, the event metadata contains the provider route data.

Model route​

Use nested model routes when one target supports multiple models. A matched model ID or alias uses its model route data.

If a nested model has no route data, it uses the target route 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: VERDICTAN_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 the two model placeholders with identifiers that are available to the provider account.

A request for the secondary model or its secondary alias sends an escalation to the specified analyst (user_id).

The primary model has no model override. Thus, it uses the target team route (team_id).

Runtime notes​

  • escalation_routing does not start an escalation. A policy must return an escalate verdict.
  • YAML does not specify a default queue. If no route data is available, the platform controls downstream handling.
  • To get the correct team or user identifier, use the Console, control plane API, verdictan team list, or verdictan user list.

Next steps​