Free Trial
Documentation menu

Client SDK: @jetty/sdk

The SDK is for when Jetty is part of an application or a CI check rather than a chat session: a typed TypeScript client that runs workflows, reads back trajectories, downloads artifacts, and labels runs. It's built around the loop Jetty is good at, run → check → fix → rerun, so the ergonomic entry point waits for a result and hands you the outputs.

Install

npm install @jetty/sdk

Requires Node 18+.

Authenticate

Construct a client with no arguments and it resolves your token the same way every Jetty tool does: an explicit argument first, then JETTY_API_TOKEN, then ~/.config/jetty/token. If none are present it throws JettyConfigError rather than failing later with a confusing 401.

import { JettyClient } from "@jetty/sdk";

// Resolves token from arg → env → ~/.config/jetty/token
const jetty = new JettyClient();

// …or pass it explicitly
const jetty2 = new JettyClient({ token: process.env.JETTY_API_TOKEN });

Run a workflow and get the result

runAndWait submits a run and polls to completion, returning a fully-resolved Trajectory. Read step outputs straight off it:

const run = await jetty.runAndWait("acme", "triage", { ticket });

const { category, priority, draft_reply } = run.steps.triage.outputs;

Need files in the run? Pass them through runWithFiles (or runAndWait's files option) and they land in the sandbox for the agent to read.

The client surface

JettyClient mirrors the product's nouns. The most-used methods:

  • Collections: listCollections, getCollection, getCollectionEnvironment, setEnvironmentVars
  • Tasks: listTasks, getTask, createTask, updateTask, deleteTask
  • Runs: runWorkflow (async), runWorkflowSync, runWithFiles, and the ergonomic runAndWait
  • Trajectories: listTrajectories, getTrajectory, getStats
  • Labels & files: addLabel, downloadFile(storageKey) → { bytes }
  • Routines: full CRUD plus runRoutineNow / listRoutineRuns
  • Step templates & trial: listStepTemplates, getStepTemplate, getTrialStatus, activateTrial

A/B evals

Because runAndWait returns structured outputs and addLabel tags the run, the SDK is the natural way to grade one agent against another and detect regressions. That's exactly what the agent-integrations example does: it runs an agent in another framework, then calls a Jetty grader runbook through the SDK and aggregates the scores.

Python

A Python SDK is planned but not yet shipped. Until it lands, Python projects can call the REST API directly, since it's a small surface and the chat-completions endpoint is OpenAI-compatible.

Source: jettyio/jetty-sdk (packages/sdk). See it drive a real eval in Bring your own framework →