Agent SDK | JoyToken | Documentation

JoyToken Agent SDK is the higher-level runtime layer for agentic workflows. It sits above the Client SDK and gives TypeScript applications a model loop, tool dispatch, stop conditions, usage aggregation, and a JoyToken provider helper.

SDKs

Language	Package	Best for
TypeScript	`@joytoken/agent-sdk-ts`	Agent loops that need tools, stop conditions, and JoyToken-governed model calls

The Agent SDK still keeps business state in your application. JoyToken governs each model call: API key, policy, routing, wallet, usage, and billing.

Agent Runtime / @joytoken/agent-sdk-ts
  -> @joytoken/client-sdk-ts
  -> JoyToken /openai/v1/chat/completions
  -> upstream model

When to use Agent SDK

Choose the Agent SDK when your application needs a loop, not just one model call.

Need	Agent SDK support
Multi-step execution	`Agent.run()` continues while the model returns tool calls
Tool definitions	`defineTool()` keeps schema and execution together
Stop conditions	`stepCountIs()`, `maxToolCalls()`, `maxCost()`
JoyToken provider	`createJoyTokenProvider()` uses the JoyToken Client SDK under the hood
Usage aggregation	Aggregates prompt, completion, total tokens, and available cost
State handoff	Accepts previous `messages` and returns updated `messages`, `steps`, and `usage`

Quick example

agent.ts

1 import {
2   Agent,
3   createJoyTokenProvider,
4   defineTool,
5   maxToolCalls,
6   stepCountIs,
7 } from "@joytoken/agent-sdk-ts";
8 
9 const lookup = defineTool({
10   name: "lookup",
11   description: "Look up internal data",
12   parameters: {
13     type: "object",
14     properties: { id: { type: "string" } },
15     required: ["id"],
16   },
17   execute: async ({ id }) => `record:${id}`,
18 });
19 
20 const agent = new Agent({
21   model: createJoyTokenProvider({
22     apiKey: process.env.JOY_TOKEN_API_KEY,
23   }),
24   modelName: "auto",
25   system: "You are concise.",
26   tier: "standard",
27   stopWhen: [stepCountIs(6), maxToolCalls(4)],
28   tools: [lookup],
29 });
30 
31 const result = await agent.run({
32   input: "Summarize record 42",
33   metadata: { workflow: "support-agent" },
34 });
35 
36 console.log(result.finalText);

Agent SDK vs Client SDK

	Agent SDK	Client SDK
Focus	Multi-step agent workflows	Direct model calls
Best for	Tools, loops, stop conditions, usage aggregation	Apps that own orchestration
Tool execution	SDK calls registered tool functions	Your application handles tool calls
State	Your app persists messages and checkpoints	Your app persists everything
Languages	TypeScript	TypeScript, Go

Next steps

Page	Contents
Usage for Agents	How coding assistants should use Agent SDK context
TypeScript SDK	Install, configure, create agents, define tools, and handle state
TypeScript API Reference	Exported classes, helpers, stop conditions, and core types