getCurrentAgent()

The getCurrentAgent() function allows you to access the current agent context from anywhere in your code, including external utility functions and libraries. This is useful when you need agent information in functions that do not have direct access to this.

Automatic context for custom methods

The framework detects and wraps custom Agent methods during initialization so getCurrentAgent() can resolve the active agent inside them and the functions they call.

How it works

import { AIChatAgent } from "@cloudflare/ai-chat";
import { getCurrentAgent } from "agents";

export class MyAgent extends AIChatAgent {
	async customMethod() {
		const { agent } = getCurrentAgent();
		// agent is automatically available
		console.log(agent.name);
	}

	async anotherMethod() {
		// This works too - no setup needed
		const { agent } = getCurrentAgent();
		return agent.state;
	}
}

import { AIChatAgent } from "@cloudflare/ai-chat";
import { getCurrentAgent } from "agents";

export class MyAgent extends AIChatAgent {
	async customMethod() {
		const { agent } = getCurrentAgent();
		// agent is automatically available
		console.log(agent.name);
	}

	async anotherMethod() {
		// This works too - no setup needed
		const { agent } = getCurrentAgent();
		return agent.state;
	}
}

No configuration is required. The framework automatically:

Scans your agent class for custom methods.
Wraps them with agent context during initialization.
Ensures getCurrentAgent() works in all external functions called from your methods.

Real-world example

import { AIChatAgent } from "@cloudflare/ai-chat";
import { getCurrentAgent } from "agents";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

// External utility function that needs agent context
async function processWithAI(prompt) {
	const { agent } = getCurrentAgent();
	// External functions can access the current agent

	return await generateText({
		model: openai("gpt-4"),
		prompt: `Agent ${agent?.name}: ${prompt}`,
	});
}

export class MyAgent extends AIChatAgent {
	async customMethod(message) {
		// Use this.* to access agent properties directly
		console.log("Agent name:", this.name);
		console.log("Agent state:", this.state);

		// External functions automatically work
		const result = await processWithAI(message);
		return result.text;
	}
}

import { AIChatAgent } from "@cloudflare/ai-chat";
import { getCurrentAgent } from "agents";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

// External utility function that needs agent context
async function processWithAI(prompt: string) {
	const { agent } = getCurrentAgent();
	// External functions can access the current agent

	return await generateText({
		model: openai("gpt-4"),
		prompt: `Agent ${agent?.name}: ${prompt}`,
	});
}

export class MyAgent extends AIChatAgent {
	async customMethod(message: string) {
		// Use this.* to access agent properties directly
		console.log("Agent name:", this.name);
		console.log("Agent state:", this.state);

		// External functions automatically work
		const result = await processWithAI(message);
		return result.text;
	}
}

Built-in vs custom methods

Built-in methods (onRequest, onEmail, onStateChanged): Already have context.
Custom methods (your methods): Automatically wrapped during initialization.
External functions: Access context through getCurrentAgent().

The context flow

// When you call a custom method:
agent.customMethod();
// → automatically wrapped with agentContext.run()
// → your method executes with full context
// → external functions can use getCurrentAgent()

// When you call a custom method:
agent.customMethod();
// → automatically wrapped with agentContext.run()
// → your method executes with full context
// → external functions can use getCurrentAgent()

Common use cases

Working with AI SDK tools

import { AIChatAgent } from "@cloudflare/ai-chat";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export class MyAgent extends AIChatAgent {
	async generateResponse(prompt) {
		// AI SDK tools automatically work
		const response = await generateText({
			model: openai("gpt-4"),
			prompt,
			tools: {
				// Tools that use getCurrentAgent() work perfectly
			},
		});

		return response.text;
	}
}

import { AIChatAgent } from "@cloudflare/ai-chat";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export class MyAgent extends AIChatAgent {
	async generateResponse(prompt: string) {
		// AI SDK tools automatically work
		const response = await generateText({
			model: openai("gpt-4"),
			prompt,
			tools: {
				// Tools that use getCurrentAgent() work perfectly
			},
		});

		return response.text;
	}
}

Calling external libraries

import { AIChatAgent } from "@cloudflare/ai-chat";
import { getCurrentAgent } from "agents";

async function saveToDatabase(data) {
	const { agent } = getCurrentAgent();
	// Can access agent info for logging, context, etc.
	console.log(`Saving data for agent: ${agent?.name}`);
}

export class MyAgent extends AIChatAgent {
	async processData(data) {
		// External functions automatically have context
		await saveToDatabase(data);
	}
}

import { AIChatAgent } from "@cloudflare/ai-chat";
import { getCurrentAgent } from "agents";

async function saveToDatabase(data: any) {
	const { agent } = getCurrentAgent();
	// Can access agent info for logging, context, etc.
	console.log(`Saving data for agent: ${agent?.name}`);
}

export class MyAgent extends AIChatAgent {
	async processData(data: any) {
		// External functions automatically have context
		await saveToDatabase(data);
	}
}

Accessing request and connection context

import { getCurrentAgent } from "agents";

function logRequestInfo() {
	const { agent, connection, request } = getCurrentAgent();

	if (request) {
		console.log("Request URL:", request.url);
		console.log("Request method:", request.method);
	}

	if (connection) {
		console.log("Connection ID:", connection.id);
	}
}

import { getCurrentAgent } from "agents";

function logRequestInfo() {
	const { agent, connection, request } = getCurrentAgent();

	if (request) {
		console.log("Request URL:", request.url);
		console.log("Request method:", request.method);
	}

	if (connection) {
		console.log("Connection ID:", connection.id);
	}
}

When context is lost

The agent context only propagates along the call tree of the original invocation. Code reached outside that call tree starts with an empty context, so getCurrentAgent() returns an object whose fields are undefined. Common cases include:

a host callback invoked through RPC from a Worker Loader child isolate, such as sandboxed Codemode execution;
a service binding or Durable Object RPC entrypoint;
a queue consumer or another entrypoint that retains an agent reference.

Route the callback through a public method on the agent. Custom methods are wrapped automatically, so calling agent.someMethod() re-enters that agent's context:

import { RpcTarget } from "cloudflare:workers";

class HostCallbackBridge extends RpcTarget {
	agent;

	constructor(agent) {
		super();
		this.agent = agent;
	}

	// Invoked through RPC from a Worker Loader child isolate. There is no context
	// ancestry. Calling a public agent method restores it automatically.
	async invoke() {
		return this.agent.handleSandboxCallback();
	}
}

export class MyMcpAgent extends McpAgent {
	async handleSandboxCallback() {
		const { agent } = getCurrentAgent();
		// `agent` is available again.
	}
}

import { RpcTarget } from "cloudflare:workers";

class HostCallbackBridge extends RpcTarget {
	agent: MyMcpAgent;

	constructor(agent: MyMcpAgent) {
		super();
		this.agent = agent;
	}

	// Invoked through RPC from a Worker Loader child isolate. There is no context
	// ancestry. Calling a public agent method restores it automatically.
	async invoke() {
		return this.agent.handleSandboxCallback();
	}
}

export class MyMcpAgent extends McpAgent {
	async handleSandboxCallback() {
		const { agent } = getCurrentAgent<MyMcpAgent>();
		// `agent` is available again.
	}
}

Context restored this way has connection, request, and email unset. It is not tied to live client I/O.

Server-initiated MCP requests (elicitInput, createMessage, and listRoots) on McpAgent do not require this indirection because the MCP transport retains its owning agent.

API reference