Insights
Building production TypeScript AI agents with HazelJS
A practical tutorial path for shipping TypeScript agents with HazelJS Agent OS — from local apply to governed tools.
This guide outlines how HumanBee engineers typically approach a first production-shaped TypeScript agent with HazelJS. It is a delivery path, not a promise that every step fits every product.
1. Start local
Install the CLI and scaffold an agent workspace:
npm install -g @hazeljs/cli
hazel new agent support-agent
cd support-agent && npm install
hazel apply
hazel apply targets a local control plane so agents can keep running after you close the terminal. See the Local Agent OS guide.
Local-first matters because you want failure modes visible on your machine before you wire production credentials.
2. Keep tools in TypeScript
Treat DNA as identity and policy — not a replacement for @Tool handlers. Real side effects stay in your code: HTTP clients, database writes, queue publishes, and domain validation.
A useful rule of thumb:
- DNA / policy — who the agent is and what it is allowed to attempt
- Tools — how side effects actually happen
- App services — shared business logic the agent should not reimplement poorly
3. Add governance early
Sensitive actions should go through authorization and, when needed, human approval. HazelJS Gatekeeper and durable HITL patterns exist for that path.
With clients, we usually classify tools into three buckets:
| Bucket | Examples | Typical control |
|---|---|---|
| Read-only | Lookup order, fetch KB article | Allow with logging |
| Reversible write | Create draft ticket | Authorize; maybe auto-run |
| Irreversible | Refund, delete, publish | Authorize + HITL |
Confidence from a model is never the same as permission.
4. Integrate business APIs deliberately
Connecting CRMs, ERPs, or internal APIs is custom engineering. Before automation:
- Document auth (OAuth, service accounts, mTLS)
- Define idempotency keys and compensating actions
- Agree sandbox vs production access
- Decide what must be audited on writes
HazelJS Skillgate can curate which APIs become agent capabilities — see Skillgate.
5. Prove recovery before launch
Kill the process mid-run. Redeploy. Expire a token. Force a tool timeout. If the agent cannot recover or surface a clear waiting state, it is not production-shaped yet.
Need help shipping?
Book a discovery call with HumanBee, or explore HazelJS docs and examples to see a full Agent OS path. Consulting is optional — HazelJS stays free and open source.