编码 Agent 使用 | JoyToken

当 Codex、Claude Code、OpenClaw、Hermes 或其他编码 Agent 修改使用 @joytoken/agent-sdk-ts 的代码时，可以把本页作为上下文。

Agent 需要知道什么

主题	指令
包选择	TypeScript Agent 循环使用 `@joytoken/agent-sdk-ts`
提供方	使用 `createJoyTokenProvider({ apiKey: process.env.JOY_TOKEN_API_KEY })`
API Key	`JOY_TOKEN_API_KEY` 只能放在服务端
工具	用 `defineTool()` 定义工具；JoyToken 不执行工具
状态	在 `Agent.run()` 前读取 messages，并保存返回的 `messages`、`steps` 和 `usage`
停止条件	将 `stepCountIs()`、`maxToolCalls()`、`maxCost()` 与 JoyToken 策略和额度一起使用

Prompt 片段

agent-instructions.md

Use @joytoken/agent-sdk-ts for JoyToken agent loops.
Create the model provider with createJoyTokenProvider({ apiKey: process.env.JOY_TOKEN_API_KEY }).
Register tools with defineTool({ name, description, parameters, execute }).
Use stopWhen: [stepCountIs(...), maxToolCalls(...)] for bounded runs.
Persist result.messages, result.steps, and result.usage in application storage.
Do not expose JOY_TOKEN_API_KEY in browser code.

审查清单

检查	为什么重要
有边界的运行循环	防止无限模型/工具循环
工具副作用审查	高风险工具动作需要应用层审批
状态持久化	Agent SDK 返回状态，但存储由应用负责
成本保护	运行时停止条件和 JoyToken 额度/策略都应该存在
请求元数据	`metadata` 应包含工作流、线程或步骤标识

常见错误

错误	修正
在每个工具里直接调用 JoyToken	工具应用于外部动作；模型调用应通过 Agent 模型提供方
把密钥放进前端代码	Agent SDK 只应在服务端使用
忽略 `stoppedBy`	记录运行结束原因，方便排障和成本复盘
把 `maxCost()` 当成唯一预算控制	同时配置 JoyToken API Key 额度、钱包和策略