Best Practices

Optimizing Cost

• Use the right model — Claude Haiku 4.5 is significantly cheaper than Opus. Use Haiku for simple tasks and reserve Sonnet/Opus for complex reasoning.
• Set maxTurns — limit the number of reasoning steps to prevent runaway conversations.
• Set maxBudgetUsd — cap per-request spend as a safety net.
• Keep system prompts concise — every token in the system prompt is sent with every message. Move detailed reference material to skills.

Skills vs System Prompt

Use the system prompt for identity, tone, and general rules (under 2,000 characters). Use skills for detailed reference material — API docs, procedures, domain knowledge. Skills are loaded on demand, reducing per-message token usage.

Security Considerations

• Never expose API keys client-side — use the token exchange pattern via createTokenHandler.
• Use permission modes appropriately — only use bypass mode for agents running in fully isolated sandboxes.
• Restrict tools — only enable the tools your agent actually needs. Disable Bash if your agent doesn't need shell access.
• Environment variables — use the dashboard to set secrets. Never hardcode them in agent code.

Testing Agents

Use the live chat preview in the dashboard to test changes iteratively. Check the Logs page to inspect conversations, token usage, and errors after testing.