TypeScript API Reference | JoyToken

Import

1 import {
2   Agent,
3   createJoyTokenProvider,
4   defineTool,
5   maxCost,
6   maxToolCalls,
7   stepCountIs,
8   type AgentOptions,
9   type AgentResult,
10   type AgentRunOptions,
11   type AgentTool,
12   type ModelProvider,
13   type ModelRequest,
14   type ModelResponse,
15   type StopCondition,
16 } from "@joytoken/agent-sdk-ts";

Agent

1 new Agent(options: AgentOptions)

Option	Type	Description
`model`	`ModelProvider`	Provider used for model calls
`modelName`	`string`	Model sent to JoyToken. Defaults to `auto`
`system`	`string`	Optional system message prepended to each run
`tools`	`AgentTool[]`	Registered tools the SDK can dispatch
`stopWhen`	`StopCondition[]`	Runtime stop conditions
`temperature`	`number`	Passed to the model provider
`maxTokens`	`number`	Sent as `max_tokens` to JoyToken
`tier`	`string`	JoyToken tier hint
`metadata`	`Record<string, unknown>`	Metadata merged into each model request

Agent.run

1 agent.run(inputOrOptions: string | AgentRunOptions): Promise<AgentResult>

Agent.run() builds the message list, calls the model provider, executes returned tool calls, appends tool results, and continues until no tool calls are returned or a stop condition matches.

1 const result = await agent.run({
2   input: "Summarize record 42",
3   messages: previousMessages,
4   metadata: { threadId: "thread-42" },
5 });

createJoyTokenProvider

1 createJoyTokenProvider(options?: JoyTokenProviderOptions): ModelProvider

Creates a ModelProvider backed by @joytoken/client-sdk-ts.

Option	Description
`apiKey`	JoyToken API key
`apiBaseUrl`	JoyToken API base URL
`openAIBaseUrl`	JoyToken OpenAI-compatible base URL
`defaultModel`	Default model when the request does not provide one

defineTool

1 defineTool<TInput = unknown, TOutput = unknown>(tool: AgentTool<TInput, TOutput>): AgentTool<TInput, TOutput>

defineTool() keeps the OpenAI-compatible schema and the execution function together.

1 const searchDocs = defineTool<{ query: string }>({
2   name: "search_docs",
3   description: "Search internal documentation",
4   parameters: {
5     type: "object",
6     properties: { query: { type: "string" } },
7     required: ["query"],
8   },
9   execute: async ({ query }, context) => {
10     return searchInternalDocs(query, context.messages);
11   },
12 });

Stop conditions

Helper	Behavior
`stepCountIs(maxSteps)`	Stops when `state.step >= maxSteps`
`maxToolCalls(maxCalls)`	Stops when tool call count reaches the limit
`maxCost(maxCredits)`	Stops when aggregated usage cost reaches the limit

Custom stop condition:

1 const stopWhen: StopCondition = (state) => ({
2   stop: state.messages.length > 40,
3   reason: "message_limit",
4 });

Core types

1 interface AgentRunOptions {
2   messages?: ChatMessage[];
3   input?: string;
4   maxSteps?: number;
5   metadata?: Record<string, unknown>;
6 }

1 interface AgentResult {
2   finalText: string;
3   messages: ChatMessage[];
4   steps: AgentStep[];
5   usage: UsageSummary;
6   stoppedBy?: string;
7 }

1 interface AgentTool<TInput = unknown, TOutput = unknown> {
2   name: string;
3   description?: string;
4   parameters?: Record<string, unknown>;
5   execute(input: TInput, context: ToolExecutionContext): Promise<TOutput> | TOutput;
6 }

1 interface UsageSummary {
2   promptTokens: number;
3   completionTokens: number;
4   totalTokens: number;
5   cost?: number;
6 }