Usage for Agents | JoyToken

Use this page when Codex, Claude Code, OpenClaw, Hermes, or another coding agent is editing code that uses @joytoken/agent-sdk-ts.

What agents should know

Topic	Instruction
Package	Use `@joytoken/agent-sdk-ts` for TypeScript agent loops
Provider	Use `createJoyTokenProvider({ apiKey: process.env.JOY_TOKEN_API_KEY })`
API key	Keep `JOY_TOKEN_API_KEY` server-side
Tools	Define tools with `defineTool()`; do not execute tools in JoyToken
State	Load messages before `Agent.run()` and persist returned `messages`, `steps`, and `usage`
Stop conditions	Use `stepCountIs()`, `maxToolCalls()`, and `maxCost()` together with JoyToken policy and quota

Prompt snippet

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.

Review checklist

Check	Why it matters
Bounded run loop	Prevents infinite model/tool loops
Tool side-effect review	High-risk tool actions need application-level approval
State persistence	Agent SDK returns state, but your app owns storage
Cost guard	Runtime stop conditions and JoyToken quota/policy should both exist
Request metadata	`metadata` should include workflow, thread, or step identifiers

Common mistakes

Mistake	Fix
Calling JoyToken directly inside every tool	Use tools for external actions; model calls should go through the Agent model provider
Storing secrets in frontend code	Keep all Agent SDK usage on the server side
Ignoring `stoppedBy`	Record why the run ended for debugging and cost review
Treating `maxCost()` as the only budget control	Also configure JoyToken API key quotas, wallet, and policy