/AYjnt/
documentation

Everything you need to ship an agent.

ayjnt is a thin framework over the Cloudflare Agents SDK. These docs walk you from your first scaffold to the last detail of the build pipeline. Read top-to-bottom to ramp up, or jump straight to the reference for daily lookups.

Start reading Source on GitHub ayjnt on npm
Quick start

From zero to running agent in four steps

  1. 01

    Install Bun

    ayjnt is Bun-first
    $curl -fsSL https://bun.com/install | bash
  2. 02

    Scaffold a project

    Minimal or with React UI
    $bunx ayjnt new my-app --with-ui
  3. 03

    Install + dev

    wrangler dev with live reload
    $cd my-app && bun install && bun run dev
  4. 04

    Deploy

    Git preflight, then wrangler deploy
    $bun run deploy
my-app/agents/counter/agent.ts ts 
import { Agent } from "agents";
import type { GeneratedEnv } from "@ayjnt/env";

type State = { count: number };

export default class CounterAgent extends Agent<GeneratedEnv, State> {
  override initialState: State = { count: 0 };

  override async onRequest(): Promise<Response> {
    return Response.json({ instance: this.name, ...this.state });
  }
}
01

Getting Started

  1. Introduction What ayjnt is, who it's for, how it relates to the Cloudflare Agents SDK.
  2. Installation Bun, Cloudflare account, and scaffolding your first project with ayjnt new.
  3. Your first agent Build a working agent end-to-end: write, run, and hit it with curl.
  4. Project anatomy Tour the generated .ayjnt/ directory and the files you author vs the files you never touch.
02

Guides

  1. File conventions agent.ts, middleware.ts, app.tsx, route groups, nested folders — the tree is the config.
  2. Agent state this.state, this.setState, persistence, and the relationship between DOs and agent instances.
  3. Routing & URL shape How folder paths become URLs, route groups, instance id parsing, HTML vs agent dispatch.
  4. Middleware Writing middleware.ts, root→leaf chaining, short-circuiting, response wrapping, context stash.
  5. Inter-agent RPC getAgent<T>(), typed DO stubs, method autocomplete, exception propagation, structured clone args.
  6. Client integration useAgent, agentFetch, the basePath gotcha, and why ayjnt's URL shape is different.
  7. Co-located React UI app.tsx next to agent.ts, the generated typed hook, and Cloudflare Assets under the hood.
  8. Agent catalog & docs.md docs.md served at <route>/docs, @callable JSDoc tags, and the access-filtered /__ayjnt/catalog endpoint.
  9. MCP agents Extending McpAgent, registering tools, streamable HTTP and SSE, Claude Desktop integration.
  10. Workflows Pair an agent with a durable Cloudflare Workflow by dropping workflow.ts — zero config, typed RPC stub, no migrations.
  11. Browser tools Zero-config browserTools(this) from ayjnt/browser — wires BROWSER, LOADER, AI, and nodejs_compat in one go.
  12. Email Define onEmail(message) and ayjnt wires Email Routing, the send_email binding, and address-based dispatch.
  13. Voice agents withVoice(Agent) + Workers AI STT/TTS, plus a generated useVoiceAgent hook that respects ayjnt's URL shape.
  14. Environment variables & secrets Reading env via this.env / c.env, typing via GeneratedEnv, .dev.vars for local dev (auto-synced into .ayjnt/dist/), wrangler secret put for production.
  15. Migrations The committed lockfile, stable agentIds, rename detection, and the git-safety contract.
  16. Deployment ayjnt deploy, git preflight checks, wrangler passthrough, environments, secrets.
03

Reference

  1. CLI Every ayjnt command: arguments, flags, exit codes, forwarded-to-wrangler flags.
  2. Runtime API Every module and export the framework provides: ayjnt, ayjnt/rpc, ayjnt/middleware, @ayjnt/*.
  3. Generated files Every file under .ayjnt/ — what it is, whether it's committed, and how it gets regenerated.
04

Troubleshooting

  1. Gotchas Every failure mode we've documented: basePath vs path, DO state persistence, RPC errors, MCP detection.

Cloudflare Agents reference

ayjnt is built on top of Cloudflare's Agents SDK. For API reference, transport details, and Cloudflare-specific features (Workers AI, D1, R2, KV bindings, etc.) consult the official docs. ayjnt is not affiliated with Cloudflare.