Quickstart

Run agents and workflows from TypeScript. It has no dependencies and is tested on Node 24.

Before the quickstart: Core is in private preview. Request access to confirm an environment and package access; the SDK is not on public npm yet.

1. Use Node.js 24 and obtain @jwtson/sdk through the supplied preview package or repository workspace. In the repository, use its pinned Node/pnpm versions, install with pnpm install --frozen-lockfile, then run pnpm build before running a script that imports the SDK.
2. Get your environment's API base URL and a server API key with permission to create/publish agents, start runs, and use the selected model. Keep the key on your server.
3. Have an administrator configure an enabled model profile and its provider credentials. Confirm connection approval, execution policy, and model-use grants. AI usage is billed by that provider.
4. Set JWTSON_API_URL to the API base URL and JWTSON_TOKEN to your key in your server environment. If the key can see several environments, pass the intended environment to Jwtson as shown below.
5. Save the example as first-agent.mjs in a project that can resolve the supplied SDK, then run node first-agent.mjs. The SDK creates and publishes the agent; you do not need to pre-create this sample agent in the console.

The example expects one usable model in the environment. If several are enabled, choose a model explicitly using the identifier reported by the SDK. If a request is refused, inspect the published agent's Access checks for the actual API key before retrying. For a console walkthrough, see Your first agent.

import { Jwtson } from '@jwtson/sdk';

const jwtson = new Jwtson(); // Reads JWTSON_API_URL and JWTSON_TOKEN

const agent = await jwtson.agents.ensure({ name: 'Summarizer', instructions: 'Summarize the text in one sentence.' });
const { text } = await agent.run('A long article...');

ensure is safe to call every time your code starts. It creates the agent if it's new, publishes a new version if you changed it, and otherwise does nothing. It compares schema content, so the API normalizing schema formatting or object-key order does not publish another version. It compares only what you pass, advanced included, so a value the API fills in by default doesn't count as a change.

If your token can see one organization, project and environment, there's nothing else to set. Otherwise name them: new Jwtson({ environment: 'Production' }). If an environment has one model you can leave model out, and if it has several the error lists them.

Streaming

const run = await agent.start('A long article...');
for await (const text of run.textStream()) process.stdout.write(text);

This works for every agent: one that doesn't stream sends its whole answer at the end. run.stream() gives the same text as events, with done carrying the final result. What's streamed can still change until the run settles it, so keep the done result rather than the text you joined up.

Output with a shape

const extractor = await jwtson.agents.ensure({
  name: 'Invoice reader',
  instructions: 'Read the invoice.',
  input: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
  output: { type: 'object', properties: { total: { type: 'number' } }, required: ['total'] },
});
const invoice = (await extractor.run({ text })).json<{ total: number }>();