> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronicle-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript

> Install the Chronicle SDK and run your first evaluation from TypeScript.

## Install

```typescript theme={null}
// npm install @chroniclelabs/sdk
import { Chronicle } from "@chroniclelabs/sdk";

const client = new Chronicle(); // reads CHRONICLE_API_KEY and CHRONICLE_API_URL
// or: new Chronicle({ apiKey: "chr_...", baseURL: "https://api.your-chronicle-deployment.com" })
```

Node.js 22 or later. Examples use ES modules and top-level `await`. Every
method returns a `Promise`, and response types are inferred. Save the complete
program as `evaluation.mts`, compile it with TypeScript configured for `NodeNext`
modules and an ES2022 target, then run the emitted `evaluation.mjs` with Node.
Install `typescript` and `@types/node` as development dependencies if your
project does not already include them.

## Run an evaluation

Before running this example, [register `billing-agent@1.0.0` and configure its
run command](/platform/agents). Set `CHRONICLE_API_KEY` and `CHRONICLE_API_URL`
using [Authentication](/api-reference/authentication). The script selects the
built-in world by its `triage-duplicate-invoice` task key; it stops if that
example is unavailable.

The keys `demo-1` and `demo-run-1` identify this first attempt. Keep them when
retrying the same inputs; change them when you want a new world or evaluation.
If task setup is not ready, keep the returned world ID and follow
[task setup recovery](/api-reference/worldsmith#retry-task-setup).

```typescript theme={null}
import { Chronicle } from "@chroniclelabs/sdk";

const client = new Chronicle();
const example = (await client.worlds.examples.list()).items.find((e) =>
  (e.blueprint.scenario.tasks ?? []).some((t) => t.key === "triage-duplicate-invoice"));
if (!example) throw new Error("The duplicate-invoice example is not available");
const preview = await client.worlds.compile({ blueprint: example.blueprint });
if (preview.problems.length) throw new Error(preview.problems.join("\n"));

let world = await client.worlds.create({ blueprint: example.blueprint, idempotencyKey: "demo-1" });
world = await client.worlds.wait(world.world.id, { timeout: 180_000 });
if (world.status !== "ready") throw new Error(`World ${world.world.id}: ${world.status}; ${world.launchError}`);
if (world.evaluation?.status !== "ready") {
  throw new Error(`Task setup is not ready for world ${world.world.id}; see the Worlds guide`);
}

let run = await client.evaluations.create({
  taskSuiteId: world.evaluation.taskSuiteId,
  agents: ["billing-agent@1.0.0"],
  idempotencyKey: "demo-run-1",
});
run = await client.evaluations.wait(run.id, { timeout: 600_000 });
if (run.status !== "succeeded") throw new Error(`Evaluation ${run.id}: ${run.status}; inspect its trials`);
const results = await client.evaluations.results(run.id);
for (const task of results.taskResults) {
  console.log(task.taskId, task.passed ? "passed" : "failed", task.failedScorers);
}
```

In the dashboard, evaluations are under **Backtests**.
[Inspect the example task](/product-explorer#agent-task) and compare it with
the [trial scores](/api-reference/evaluations#inspect-trials).

To see individual scores, iterate the trials:

```typescript theme={null}
for await (const trial of await client.evaluations.trials.list(run.id)) {
  console.log(trial.agent, trial.taskId, trial.status);
  for (const score of trial.scores) console.log("  ", score.name, score.score, score.passed);
}
```

## Errors and configuration

```typescript theme={null}
import { APIError, Chronicle } from "@chroniclelabs/sdk";

const client = new Chronicle({ timeout: 30_000, maxRetries: 2 });

try {
  await client.worlds.retrieve("<world-id>");
} catch (e) {
  if (e instanceof APIError) console.error(e.statusCode, e.message, e.requestId);
  throw e;
}
```

Timeouts are in milliseconds. Pages are async iterables and also have `items`,
`hasNextPage()`, and `getNextPage()`. Params and fields are `camelCase`; all
types are exported from the package. See [Errors and retries](/api-reference/reliability).