Escalations

Create, read, and decide on escalations from the SDK.

Escalations

The escalations resource covers the full lifecycle. Creating escalations uses a workspace apiKey; the read and reviewer methods act on behalf of a user, so use a client built with token or getToken (see Client).

escalate

Convenience wrapper that creates an escalation under a policy. The policy key is the first argument; everything else is the decision content.

const escalation = await tryagent.escalate("orders.auth_doc", {
  agentId: "order-agent",
  runId: "run_4821",
  subject: { type: "order", id: "ord_4821", label: "Order #4821" },
  question: "The authorization document is missing a signature date. Continue?",
  evidence: [
    "Candidate name is present.",
    "Employer is present.",
    "Signature date is blank.",
  ],
  choices: [
    { id: "manual_review", label: "Send to manual review" },
    { id: "continue", label: "Continue anyway" },
  ],
  resume: {
    mode: "webhook",
    url: "https://api.example.com/tryagent/resume",
    secret: process.env.TRYAGENT_WEBHOOK_SECRET!,
  },
});

console.log(escalation.id, escalation.status); // esc_..., "open"

escalate returns as soon as TryAgent creates the escalation — it does not wait for a reviewer. Required fields are agentId, runId, subject, question, evidence, and choices. Optional fields include responseFields, severity, resume, and metadata.

escalations.create

The same call as escalate, with policy included in the input object. Use it when you already have a fully assembled CreateEscalationInput.

const escalation = await tryagent.escalations.create({
  policy: "orders.auth_doc",
  agentId: "order-agent",
  runId: "run_4821",
  // ...the remaining decision content
});

escalations.list

Returns escalations for the workspace, optionally filtered by status. Resolves to an Escalation[] (the SDK unwraps the API envelope).

const open = await tryagent.escalations.list({ status: "open" });

status accepts open, acknowledged, decided, resolved, breached, or canceled. Omit it to list all.

escalations.get

Fetch a single escalation by id, including its current status, decision, and learned recommendation when present.

const escalation = await tryagent.escalations.get("esc_123");

escalations.acknowledge

Mark an open escalation as being worked on. Only open escalations can be acknowledged.

await tryagent.escalations.acknowledge("esc_123");

escalations.decide

Record a reviewer decision and resolve the escalation. choice must match one of the escalation’s choice ids. Include response when the escalation defined responseFields.

await tryagent.escalations.decide("esc_123", {
  choice: "continue",
  reason: "Signature verified out of band.",
  response: { approvedLimit: 5000, riskLevel: "low" },
});

Deciding triggers the signed resume callback to your resume.url. Verify it with webhooks.constructEvent.

escalations.cancel

Cancel an escalation without recording a choice — for example, when the underlying run is abandoned.

await tryagent.escalations.cancel("esc_123", { reason: "Order withdrawn." });

Both decide and cancel reject escalations already in a terminal state (decided, resolved, breached, canceled).