TypeScript SDK

@joytoken/agent-sdk-ts is a lightweight TypeScript runtime for multi-step agents. It uses @joytoken/client-sdk-ts for model calls and keeps tool execution, state storage, permissions, and human approval in your application.

Install

$pnpm add @joytoken/agent-sdk-ts

For monorepo development:

joytoken-sdks
$pnpm install
$pnpm build

Create a provider

provider.ts
1import { createJoyTokenProvider } from "@joytoken/agent-sdk-ts";
2
3export const model = createJoyTokenProvider({
4 apiKey: process.env.JOY_TOKEN_API_KEY,
5 defaultModel: "auto",
6});

Define tools

tools.ts
1import { defineTool } from "@joytoken/agent-sdk-ts";
2
3export const lookup = defineTool<{ id: string }>({
4 name: "lookup",
5 description: "Look up internal data",
6 parameters: {
7 type: "object",
8 properties: { id: { type: "string" } },
9 required: ["id"],
10 },
11 execute: async ({ id }, context) => {
12 return `record:${id}:step:${context.step}`;
13 },
14});

Create an agent

agent.ts
1import { Agent, maxToolCalls, stepCountIs } from "@joytoken/agent-sdk-ts";
2import { model } from "./provider";
3import { lookup } from "./tools";
4
5export const agent = new Agent({
6 model,
7 modelName: "auto",
8 system: "You are concise.",
9 tier: "standard",
10 tools: [lookup],
11 stopWhen: [stepCountIs(6), maxToolCalls(4)],
12 metadata: {
13 workflow: "support-agent",
14 },
15});

Run the agent

run.ts
1const result = await agent.run({
2 input: "Summarize record 42",
3 metadata: {
4 threadId: "thread-42",
5 },
6});
7
8console.log(result.finalText);
9console.log(result.usage);

Agent.run() returns finalText, messages, steps, usage, and optionally stoppedBy.

Persist state

state.ts
1const thread = await db.agentThreads.load(threadId);
2
3const result = await agent.run({
4 input: userInput,
5 messages: thread.messages,
6 metadata: { threadId },
7});
8
9await db.agentThreads.save(threadId, {
10 messages: result.messages,
11 steps: result.steps,
12 usage: result.usage,
13 stoppedBy: result.stoppedBy,
14});

JoyToken does not store agent memory. Your application owns thread state, tool results, checkpoints, permissions, and audit records.

Stop conditions

stop.ts
1import { maxCost, maxToolCalls, stepCountIs } from "@joytoken/agent-sdk-ts";
2
3const stopWhen = [
4 stepCountIs(8),
5 maxToolCalls(20),
6 maxCost(25),
7];

Combine runtime stop conditions with JoyToken API key quota, wallet, and policy controls.

Validate

joytoken-sdks
$pnpm build
$pnpm --filter @joytoken/agent-sdk-ts test