TypeScript SDK

@joytoken/agent-sdk-ts 是一个轻量 TypeScript 多步 Agent runtime。它使用 @joytoken/client-sdk-ts 调用模型,并把工具执行、状态存储、权限和人工审批留在你的应用里。

安装

$pnpm add @joytoken/agent-sdk-ts

Monorepo 开发:

joytoken-sdks
$pnpm install
$pnpm build

创建提供方

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

定义工具

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

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

运行 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() 返回 finalTextmessagesstepsusage,以及可选的 stoppedBy

持久化状态

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 不存储 Agent 记忆。线程状态、工具结果、检查点、权限和审计记录都由你的应用管理。

停止条件

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

运行时停止条件应与 JoyToken API Key 额度、钱包和策略一起使用。

验证

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