@callable decorator doesn't implement __unsafe_ensureInitialized()

[dragonkhoi]

onStart() only runs if ensureInitialized is called via Workflow RPC, WebSocket, Fetch, Alarm, wake up, etc. As listed in #1056 :

'In PartyServer, #ensureInitialized() guards were added to fetch(), alarm(), webSocketMessage(), webSocketClose(), and webSocketError(). But _workflow_handleCallback(), _workflow_broadcast(), and _workflow_updateState() are public methods on the Agent class that get called via native Cloudflare DO RPC — they bypass all of those guarded entry points."

Similarly, @callable RPC methods defined by user (eg me) run and onStart() hasn't run yet. Would it be possible to add ensureInitialized guard in callable as well? Currently, I have to put onStart at the top of every callable that needs it (eg SQL table to exist). I know in #1057 this was fixed for workflows specifically but callable is also a native Cloudflare DO RPC which bypasses the entry points.

[threepointone]

Are you using getAgentByName to connect to the agent?

[threepointone]

or routeAgentRequest?

[threepointone]

I ask because using either of those explicitly triggers initialisation. I'd love to see a repro if that's not the case.

[dragonkhoi]

I am not, I am calling idFromName and .get as a normal DO RPC from an OpenNext backend API route. I have tried really hard and not sure if skill issue 😅 , but I can't get getAgentByName or routeAgentRequest working since I'm trying to directly RPC the Agent DO from an OpenNext backend. This keeps erroring during yarn deploy, next build, due to cloudflare:workers and cloudflare:email not being available as per opennextjs/opennextjs-cloudflare#578, you can't use cloudflare:* modules in OpenNext.

I've tried dynamic importing, and even hackily patching the esbuild bundle-server.js to mark cloudflare:workers/email as external and use a dynamic require, but I get (error) Error: Failed to load external module cloudflare:workers: Error: Dynamic require of "cloudflare:workers" is not supported

From OpenNext, I am going to try stub.fetch('agents/[agent-name]/[instance-id]') and use routeAgentRequest and let you know if that works.

[dragonkhoi]

OK found a fix, so instead of binding the DO directly from OpenNext and calling it via RPC... I have a Open Next project and a separate Worker + DO. I bind the Worker to a service binding (AGENT_SERVICE) in the OpenNext backend. In my API route, I use the service binding for .fetch using the Agent Routing url.

/**
 * Helper to call Agent methods via the agent service binding.
 *
 * Requests go through the agent worker's agentsMiddleware, which
 * routes to the correct DO instance and triggers the full Agent lifecycle
 * (including onStart).
 */
export function getAgentStub(env: CloudflareEnv, instanceId: string) {
  const base = `https://internal/agents/[agent-name]/${instanceId}`;

  return {
    /** Call a method on the Agent via its onRequest HTTP handler. */
    async call<T = unknown>(method: string, args?: unknown): Promise<T> {
      const res = await env.AGENT_SERVICE.fetch(`${base}/rpc/${method}`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(args ?? {}),
      });
      if (!res.ok) {
        throw new Error(`Agent.${method} failed: ${res.status} ${await res.text()}`);
      }
      return res.json() as Promise<T>;
    },
  };
}

Then in the Worker, I use hono agentsMiddleware, which will route it to the instance of the right agent. This triggers onRequest in my Agent class, where I parse the URL to do the function I want. Unfortunately, this means no nice typescript RPCs, but it seems to be the only way to make it work so far.

Not sure if I have a proposal to improve this but hope this works for anyone else who is trying to call an Agent from OpenNext with correct initialization.

[threepointone]

unfortunately, this is just because of how opennext works, in dev it doesn't use workerd but node.js, so that cloudflare specific stuff doesn't work. it's one of the reasons why we built vinext, this would "just work" there (see https://github.com/threepointone/next-agents) I'm glad you got a workaround, lemme keep this open for a bit, we might update docs for this with more details.