@tryagent/sdk

TypeScript SDK for creating TryAgent escalations from AI agents and workflows.

Use TryAgent when an agent reaches a decision it should not make alone. Your code sends the decision point, evidence, choices, and resume target. TryAgent routes the escalation to the right reviewers, records the decision or timeout path, and calls your workflow back when it can continue.

Full documentation: https://tryagentai.mintlify.app/quickstart

Install

pnpm add @tryagent/sdk

npm install @tryagent/sdk

Prerequisites

Before calling the SDK, create these in TryAgent:

• A workspace API key, available to your runtime as TRYAGENT_API_KEY.
• An escalation policy key, such as orders.auth_doc.
• A resume webhook endpoint if your workflow should continue after the reviewer decides.

Create a client

import { TryAgent } from "@tryagent/sdk";

const tryagent = new TryAgent({
  apiKey: process.env.TRYAGENT_API_KEY!,
});

The SDK defaults to https://api.tryagent.ai. Pass baseUrl only for local development or tests.

const tryagent = new TryAgent({
  apiKey: process.env.TRYAGENT_API_KEY!,
  baseUrl: "http://localhost:4000",
});

Send an escalation

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" },
  ],
  responseFields: [
    {
      type: "number",
      name: "approvedLimit",
      label: "Approved limit",
      min: 0,
      step: 0.01,
    },
    {
      type: "select",
      name: "riskLevel",
      label: "Risk level",
      options: [
        { value: "low", label: "Low" },
        { value: "high", label: "High" },
      ],
    },
  ],
  resume: {
    mode: "webhook",
    url: "https://api.example.com/tryagent/resume",
    secret: process.env.TRYAGENT_WEBHOOK_SECRET!,
  },
});

console.log(escalation.id, escalation.status);

escalate returns as soon as TryAgent creates the escalation. It does not wait for a human reviewer. Store the returned escalation ID if you want to correlate logs or audit records.

Resume your workflow

When a reviewer decides, or the policy timeout path applies, TryAgent sends a POST request to resume.url. Use the event's runId to load and continue the paused workflow. If you configured responseFields, the callback includes the validated structured values as response.

When resume.secret is set, TryAgent signs the exact JSON body with HMAC-SHA256 and includes:

• x-tryagent-event: escalation.decided
• x-tryagent-delivery: resume:<escalation id>
• x-tryagent-signature: v1=<hex hmac>

Verify the signature before applying the decision. webhooks.constructEvent verifies the HMAC (constant-time, via Web Crypto so it runs on Node, edge, and Workers) and returns the typed event, throwing WebhookSignatureError when verification fails. Always pass the raw request body — re-serializing JSON changes the bytes and breaks the signature.

import { WebhookSignatureError } from "@tryagent/sdk";

export async function POST(request: Request) {
  const body = await request.text();

  try {
    const event = await tryagent.webhooks.constructEvent({
      payload: body,
      signature: request.headers.get("x-tryagent-signature"),
      secret: process.env.TRYAGENT_WEBHOOK_SECRET!,
    });

    await resumeWorkflow(event.runId, { choice: event.choice });
    return Response.json({ ok: true });
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      return Response.json({ error: "Invalid signature" }, { status: 401 });
    }
    throw error;
  }
}

See the quickstart for the full callback handler.

Read and manage escalations

Beyond escalate, the escalations resource exposes the rest of the lifecycle:

await tryagent.escalations.list({ status: "open" });
await tryagent.escalations.get(escalationId);
await tryagent.escalations.acknowledge(escalationId);
await tryagent.escalations.decide(escalationId, { choice: "continue", reason: "Verified" });
await tryagent.escalations.cancel(escalationId, { reason: "Duplicate" });

These methods work with an ain_live_ API key as long as the key carries the matching scope, or with a workspace user token/getToken. API-key scopes:

| Method | Required scope | | --- | --- | | escalate / create | escalations:write | | list, get | escalations:read | | acknowledge | escalations:acknowledge | | decide | escalations:decide | | cancel | escalations:cancel |

Keys are issued with all escalation scopes by default, so every method works out of the box. To restrict a key, pass a narrower scopes array to POST /api-keys; a call that needs a scope the key lacks returns 403.

Handle errors

Non-2xx API responses and network failures throw ApiError.

import { ApiError } from "@tryagent/sdk";

try {
  await tryagent.escalate("orders.auth_doc", input);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.status, error.requestId, error.body);
    throw error;
  }

  throw error;
}