Skip to main content

uip agent escalation

uip agent escalation manages escalation resources on an agent project — the human-in-the-loop (HITL) hooks the agent can raise at runtime to request approval, clarification, or review from a human operator. Escalations are persisted alongside tools and contexts as agent resources.

Purely local — no login required.

Synopsis​

uip agent escalation add    <name> [--description <text>] [--type <type>] [--path <dir>]
uip agent escalation list                                                  [--path <dir>]
uip agent escalation remove <name>                                         [--path <dir>]

All subcommands honor the global options (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

uip agent escalation add​

Add an escalation resource.

Arguments​

  • <name> (required) — Escalation name.

Options​

FlagDefaultPurpose
--description <desc>—Human-readable description, stored on the resource.
--type <type>EscalationEscalation type. Known values: Escalation, VsEscalation. Other values may be accepted — run uip agent escalation add --help for the current list.
--path <path>.Path to the agent project directory.

Examples​

# Simplest — default Escalation type
uip agent escalation add ApprovalRequired --path ./my-agent

# With description
uip agent escalation add ApprovalRequired \
  --description "Require human approval before executing refund" \
  --path ./my-agent

# VsEscalation (Studio Desktop action-center flavour)
uip agent escalation add Review --type VsEscalation --path ./my-agent

Data shape (--output json)​

{
  "Code": "AgentEscalationAdd",
  "Data": {
    "Status": "Escalation added",
    "Name": "ApprovalRequired",
    "Type": "Escalation",
    "Id": "a1b2c3d4-0000-0000-0000-000000000020"
  }
}

Id is a generated UUID. Use either Name or Id with escalation remove.

uip agent escalation list​

Enumerate the escalation resources configured on the agent.

Options​

FlagDefaultPurpose
--path <path>.Path to the agent project directory.

Example​

uip agent escalation list --path ./my-agent

Data shape (--output json)​

{
  "Code": "AgentEscalationList",
  "Data": [
    {
      "Name": "ApprovalRequired",
      "Type": "Escalation",
      "Id": "a1b2c3d4-0000-0000-0000-000000000020"
    }
  ]
}

Empty projects return Data: { "Message": "No escalations configured" }.

uip agent escalation remove​

Remove an escalation resource.

Arguments​

  • <name> (required) — Escalation name or ID.

Options​

FlagDefaultPurpose
--path <path>.Path to the agent project directory.

Example​

uip agent escalation remove ApprovalRequired --path ./my-agent

Data shape (--output json)​

{
  "Code": "AgentEscalationRemove",
  "Data": {
    "Status": "Escalation removed",
    "Name": "ApprovalRequired"
  }
}

A missing escalation fails with Escalation "<name>" not found and exit code 1.

See also​