getCurrentAgent()

import { TypeScriptExample } from "~/components";

getCurrentAgent() returns the Durable Object that is handling the current invocation, along with its request or WebSocket connection. Use it in shared code that does not have access to this, such as a tool, a logging helper, or a library function.

import { DurableObject } from "cloudflare:workers";
import { getCurrentAgent, Lifecycle } from "agents/lifecycle";

function requestOrigin(): string | undefined {
	const { request } = getCurrentAgent();
	return request ? new URL(request.url).origin : undefined;
}

export class MyAgent extends DurableObject<Env> {
	readonly lifecycle = Lifecycle.install(this);

	onRequest(): Response {
		return Response.json({ origin: requestOrigin() });
	}

	greeting(): string {
		return "hello";
	}
}

export function greet(): string | undefined {
	const { agent } = getCurrentAgent<MyAgent>();
	return agent?.greeting();
}

Pass your class as the type parameter when shared code needs its methods, as greet() does. Without a type parameter, agent is typed as a LifecycleObject. Inside your own class, prefer this.

Return value

getCurrentAgent<Host>() returns a CurrentAgentContext<Host>:

Every value is undefined outside an invocation that the Lifecycle started. Check agent before you use it.

Context availability

The Lifecycle sets the context while it calls host hooks and user callbacks:

Scheduler callbacks run from the alarm, in a fresh invocation. They do not see the request or connection that created the schedule:

import { DurableObject } from "cloudflare:workers";
import { getCurrentAgent, Lifecycle } from "agents/lifecycle";
import { Scheduler } from "agents/schedules";

function log(message: string): void {
	const { agent } = getCurrentAgent<Reminders>();
	console.log(`[${agent?.lifecycle.name}] ${message}`);
}

export class Reminders extends DurableObject<Env> {
	readonly scheduler = new Scheduler({
		callbacks: {
			remind: (payload: { text: string }) => log(payload.text),
		},
	});
	readonly lifecycle = Lifecycle.install(this).use(this.scheduler);

	async onRequest(): Promise<Response> {
		await this.scheduler.set(60, "remind", { text: "Stand up" });
		return new Response("Scheduled", { status: 202 });
	}
}

Capability hooks

Capability hooks run with the context cleared, not inherited from whatever called them. A capability that calls user code wraps the call in this.lifecycle.runInHostContext(), so getCurrentAgent() returns the host inside the callback. A capability that owns a connection or request can pass it as the second argument. For more information, refer to Build a capability.

Native RPC and other entry points

The context only follows the call tree of an invocation that the Lifecycle started. The Lifecycle does not wrap native Durable Object RPC methods, so getCurrentAgent() returns undefined values inside them and in everything they call. The same is true for code reached through a service binding, a Worker Loader child isolate, or another entry point that holds a reference to the object.

On the Agent class

getCurrentAgent() from agents is the same function, typed for the Agent class. The Agent class sets more context than a plain Lifecycle object:

• Custom methods. The Agent class wraps your class's own methods during initialization, so getCurrentAgent() works inside them and in every function they call, including when they run over RPC. To restore the context from a callback that arrives through RPC, call a public method on the agent. Context restored this way has connection, request, and email unset.
• Email. Inside onEmail(), email holds the incoming email.
• Connections. Inside onConnect() and onMessage(), connection holds the calling WebSocket connection.

For more information, refer to Agent class.