TypeScript API 参考 | JoyToken

导入

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)

选项	类型	说明
`model`	`ModelProvider`	用于模型调用的提供方
`modelName`	`string`	发送给 JoyToken 的模型名。默认 `auto`
`system`	`string`	每次运行前置的可选 system message
`tools`	`AgentTool[]`	SDK 可以调度的注册工具
`stopWhen`	`StopCondition[]`	运行时停止条件
`temperature`	`number`	传给模型提供方
`maxTokens`	`number`	以 `max_tokens` 发送给 JoyToken
`tier`	`string`	JoyToken tier hint
`metadata`	`Record<string, unknown>`	合并到每次模型请求的元数据

Agent.run

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

Agent.run() 会构建 message list、调用模型提供方、执行模型返回的工具调用、追加工具结果，并持续运行到模型不再返回工具调用或命中停止条件。

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

创建一个基于 @joytoken/client-sdk-ts 的 ModelProvider。

选项	说明
`apiKey`	JoyToken API Key
`apiBaseUrl`	JoyToken API 基础 URL
`openAIBaseUrl`	JoyToken OpenAI 兼容基础 URL
`defaultModel`	请求没有提供 model 时使用的默认模型

defineTool

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

defineTool() 把 OpenAI 兼容 schema 和执行函数放在一起。

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 });

停止条件

Helper	行为
`stepCountIs(maxSteps)`	当 `state.step >= maxSteps` 时停止
`maxToolCalls(maxCalls)`	当工具调用次数达到限制时停止
`maxCost(maxCredits)`	当聚合用量成本达到限制时停止

自定义停止条件：

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

核心类型

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 }