Skip to content
Cloudflare Docs

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

All custom methods automatically have full agent context. The framework automatically detects and wraps your custom methods during initialization, ensuring getCurrentAgent() works everywhere.

How it works

JavaScript
import { AIChatAgent } from "agents/ai-chat-agent";
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:

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

Real-world example

JavaScript
import { AIChatAgent } from "agents/ai-chat-agent";
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;
  }
}

Built-in vs custom methods

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

The context flow

JavaScript
// 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

JavaScript
import { AIChatAgent } from "agents/ai-chat-agent";
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;
  }
}

Calling external libraries

JavaScript
import { AIChatAgent } from "agents/ai-chat-agent";
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);
  }
}

Accessing request and connection context

JavaScript
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);
  }
}

API reference

getCurrentAgent()

Gets the current agent from any context where it is available.

JavaScript
import { getCurrentAgent } from "agents";

Returns:

PropertyTypeDescription
agentT | undefinedThe current agent instance
connectionConnection | undefinedThe WebSocket connection (if called from a WebSocket handler)
requestRequest | undefinedThe HTTP request (if called from a request handler)
emailAgentEmail | undefinedThe email (if called from an email handler)

Usage:

JavaScript
import { AIChatAgent } from "agents/ai-chat-agent";
import { getCurrentAgent } from "agents";


export class MyAgent extends AIChatAgent {
  async customMethod() {
    const { agent, connection, request } = getCurrentAgent();
    // agent is properly typed as MyAgent
    // connection and request available if called from a request handler
  }
}

Context availability

The context available depends on how the method was invoked:

Invocationagentconnectionrequestemail
onRequest()YesNoYesNo
onConnect()YesYesYesNo
onMessage()YesYesNoNo
onEmail()YesNoNoYes
Custom method (via RPC)YesYesNoNo
Scheduled taskYesNoNoNo
Queue callbackYesDependsDependsDepends

Best practices

  1. Use this when possible: Inside agent methods, prefer this.name, this.state, etc. over getCurrentAgent().

  2. Use getCurrentAgent() in external functions: When you need agent context in utility functions or libraries that do not have access to this.

  3. Check for undefined: The returned values may be undefined if called outside an agent context.

    JavaScript
    const { agent } = getCurrentAgent();
    if (agent) {
      // Safe to use agent
      console.log(agent.name);
    }

  4. Type the agent: Pass your agent class as a type parameter for proper typing.

    JavaScript
    const { agent } = getCurrentAgent();
    // agent is typed as MyAgent | undefined

Next steps

Agents API Complete API reference for the Agents SDK.
Callable methods Expose methods to clients via RPC.
State management Manage and sync agent state.