Agent API

Agent<State>

Pass only the synchronized state shape. Ayjnt owns and augments the generated environment, so you do not thread GeneratedEnv through every class. The optional second generic is initialization props.

Use the direct Cloudflare Agent<Env, State, Props> import when you intentionally want to own the complete environment type yourself.

import { Agent, callable } from "ayjnt";

type State = { count: number };

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

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

Use the upstream class when you need it

Ayjnt discovers the default export from agent.ts, so that class may extend either Ayjnt’s wrapper or Cloudflare’s class. CloudflareAgent is the unchanged upstream export; use it when explicitly controlling the full environment generic matters more than Ayjnt’s class-safe peer and co-located workflow helpers.

import { CloudflareAgent } from "ayjnt";

interface Env extends Cloudflare.Env {
  PRIVATE_SERVICE: Service;
}

type State = { ready: boolean };

export default class AdvancedAgent
  extends CloudflareAgent<Env, State> {
  initialState: State = { ready: false };
}

agent(TargetClass, name?, options?)

Returns a typed handle to another top-level agent instance. Import the target class as a value; it supplies autocomplete and is the runtime key for Ayjnt’s generated constructor-to-binding registry.

The namespace overload remains available for custom Durable Object bindings: this.agent(this.env.CUSTOM, name).

import { Agent } from "ayjnt";
import InventoryAgent from "../inventory/agent";

export default class OrdersAgent extends Agent {
  async placeOrder(sku: string, quantity: number) {
    const inventory = await this.agent(InventoryAgent, "primary");
    return inventory.reserve(sku, quantity);
  }
}

workflow(params)

Starts the workflow.ts beside this agent. Ayjnt generates the binding and parameter relationship, so there is no mixin or string binding name. The returned string is the workflow instance ID.

const workflowId = await this.workflow({
  documentId,
  requestedBy: this.name,
});

createSession() and createSessionManager()

createSession(id?) creates an upstream Cloudflare Session backed by this agent’s SQLite. createSessionManager() manages multiple named conversations, branches, archives, and compaction.

export default class AssistantAgent extends Agent {
  session = this.createSession("support")
    .withContext("identity", {
      provider: { get: async () => "You are a support assistant." },
    });

  async history() {
    return this.session.getHistory();
  }
}

Inherited capabilities