Runtime SyntaxError for typescript 5.8.3 with openai/agents v0.0.12 at agents-core with node v22 locally and AWS lambda

[cam-nano]

Please read this first

• Have you read the docs? Agents SDK docs

Yes

• Have you searched for related issues? Others may have faced similar issues.

Closest one I could find was: #213

Describe the bug

Getting the issue when using the @openai/agent with a lambda (node22x) and locally (node v22.12.0). I have tried all sorts of permutations of tsconfig and removing dependencies but am still getting this error. I have a test repo for this issue that I can make public if needed.

{
  "errorType": "Runtime.UserCodeSyntaxError",
  "errorMessage": "SyntaxError: Cannot use import statement outside a module",
  "trace": [
    "Runtime.UserCodeSyntaxError: SyntaxError: Cannot use import statement outside a module",
    "    at _loadUserApp (file:///var/runtime/index.mjs:1106:17)",
    "    at async UserFunction.js.module.exports.load (file:///var/runtime/index.mjs:1148:21)",
    "    at async start (file:///var/runtime/index.mjs:1332:23)",
    "    at async file:///var/runtime/index.mjs:1339:1"
  ]
}

Getting a similar issue when running locally with node v22.12.0 as a unit test:

 /Users/cam/Documents/user/dev/test-openai/node_modules/@openai/agents/dist/index.js:1
    import { setDefaultModelProvider } from '@openai/agents-core';
    ^^^^^^

    SyntaxError: Cannot use import statement outside a module

    > 1 | import { Agent, run, setDefaultOpenAIKey } from '@openai/agents';
        | ^
      2 | import { OPENAI_API_KEY } from "../constants";
      3 | import { ClientError } from '../utils/client-error';
      4 |

      at Runtime.createScriptFromCode (node_modules/jest-runtime/build/index.js:1314:40)
      at Object.<anonymous> (src/commands/process-agent-command.ts:1:1)
      at Object.<anonymous> (tests/agent-command.test.ts:1:1)

I have created a 'skinny' repo with only the handler, command and test in it and am getting the same result as in my larger app.

Debug information

• Agents SDK version: (e.g. v0.0.1)

"@openai/agents": "^0.0.12",

• Runtime environment (e.g. Node.js 22.16.0)

locally: v22.12.0
AWS lambda: node22x

Repro steps

tsconfig:

{
  "compilerOptions": {
    "declaration": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "isolatedModules": true,
    "outDir": "../lib",
    "removeComments": true,
    "sourceMap": true,
    "strictPropertyInitialization": false,
  },

  "extends": "@tsconfig/node22/tsconfig.json",
  "exclude": ["../tests/**/*.ts"]
}

Command:

import { Agent, run, setDefaultOpenAIKey } from '@openai/agents';
import { OPENAI_API_KEY } from "../constants";
import { ClientError } from '../utils/client-error';


export interface ProcessAgentCommandParams {
    userId: string;
    ledgerId?: string;
    question: string;
}

export interface ProcessAgentCommandResponse {
    answer?: string;
}

export class ProcessAgentCommand {
    params: ProcessAgentCommandParams;
    agent: Agent;
    
    private constructor(params: ProcessAgentCommandParams) {
        this.params = params;
        setDefaultOpenAIKey(OPENAI_API_KEY!);        
    }

    public static async build(params: ProcessAgentCommandParams): Promise<ProcessAgentCommand | ClientError> {
        const command = new ProcessAgentCommand(params)
        return command;
    }

    public async execute(): Promise<ProcessAgentCommandResponse> {
        const result = await run(
            this.agent,
            this.params.question,
        );
        console.log(result.finalOutput);

        return {
            answer: result.finalOutput,
        }
    }        
}

test

import { ProcessAgentCommand } from "../src/commands/process-agent-command";
import { ClientError } from "../src/utils/client-error";

describe('Agent Test', () => {
    it('should test the agent command', async () => {

        const command = await ProcessAgentCommand.build({
            userId: 'some-user-id',
            ledgerId: 'some-ledger-id',
            question: 'What is the capital of France?',
        });
        if (command instanceof ClientError) {
            console.error('Error building command:', command);
            return;
        }
        const result = await command.execute();
        console.log('Command executed successfully:', result);
    });
});

package.json dependencies, I have them in a skinny repo to try and isolate if a dependency is causing the issue:

{
   "dependencies": {
        "@openai/agents": "^0.0.12",
        "@types/aws-lambda": "^8.10.152",
        "uuid": "^11.1.0",
        "zod": "<=3.25.67"
    },
    "devDependencies": {
        "@aws-sdk/credential-providers": "3.848.0",
        "@aws-sdk/types": "3.840.0",
        "@tsconfig/node22": "22.0.2",
        "@types/jest": "^30.0.0",
        "@types/node": "^24.0.5",
        "aws-sdk-client-mock": "^4.1.0",
        "eslint": "9.31.0",
        "jest": "30.0.4",
        "prettier": "3.6.2",
        "ts-jest": "29.4.0",
        "typescript": "5.8.3",
        "typescript-eslint": "8.38.0"
    }
}

Expected behavior

I would expect there not to be "SyntaxError: Cannot use import statement outside a module" at " import { setDefaultModelProvider } from '@openai/agents-core';" when the runtime typescript is executed

[seratch]

I tried to reproduce the issue locally, but I was not able to see the same. Tested with Node v22.16.0.

package.json:

{
  "name": "issue-245",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node lib/index.js",
    "build": "tsc"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@openai/agents": "^0.0.12"
  },
  "devDependencies": {
    "@tsconfig/node22": "^22.0.2"
  }
}

tsconfig.json:

{
  "compilerOptions": {
    "declaration": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "isolatedModules": true,
    "outDir": "lib",
    "removeComments": true,
    "sourceMap": true,
    "strictPropertyInitialization": false
  },
  "extends": "@tsconfig/node22/tsconfig.json"
}

index.ts:

import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant.",
});

async function main() {
  const result = await run(
    agent,
    "Write a haiku about recursion in programming."
  );
  console.log(result.finalOutput);
}

main().catch(console.error);

[cam-nano]

Hi, thanks for looking into this. The command code I am using outputs the expected result when compiled and run in index.js like in your example above.

The use cases where it is failing is:

• running this code from jest
• running this code in a lambda

If I put your working code into a jest test I am getting the import error result:

import { Agent, run } from "@openai/agents";

describe('Agent Haiku Test', () => {
    it('should test the agent haiku', async () => {
        const agent = new Agent({
            name: "Assistant",
            instructions: "You are a helpful assistant.",
        });

        async function main() {
            const result = await run(
                agent,
                "Write a haiku about recursion in programming."
            );
            console.log(result.finalOutput);
        }
        main().catch(console.error);

    });
});

This is getting the output:

    /Users/cam/Documents/user/dev/test-openai/node_modules/@openai/agents/dist/index.js:1
    import { setDefaultModelProvider } from '@openai/agents-core';
    ^^^^^^

    SyntaxError: Cannot use import statement outside a module

    > 1 | import { Agent, run } from "@openai/agents";
        | ^
      2 |
      3 | describe('Agent Haiku Test', () => {
      4 |     it('should test the agent haiku', async () => {

      at Runtime.createScriptFromCode (node_modules/jest-runtime/build/index.js:1314:40)
      at Object.<anonymous> (tests/agent-main.test.ts:1:1)

Which is the same error when run in a lambda container. If I put the working code from your example directly into a lambda handler function:

import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import { HEADERS } from '../constants';
import { Agent, run } from "@openai/agents";

export async function heartbeatGetHandler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {

    const params = event?.queryStringParameters;

    let message = 'No answer provided';

    const agent = new Agent({
        name: "Assistant",
        instructions: "You are a helpful assistant.",
    });

    async function main() {
        const result = await run(
            agent,
            "Write a haiku about recursion in programming."
        );
        console.log(result.finalOutput);
        message = result.finalOutput || 'No answer provided';
    }
    main().catch(console.error);

    const result = {
        params: params || {},
        message: message,
        timestamp: new Date().toISOString(),
    }

    return {
        statusCode: 200,
        headers: HEADERS,
        body: JSON.stringify(result),
    };
}

The output is:

{
  "errorType": "Runtime.UserCodeSyntaxError",
  "errorMessage": "SyntaxError: Cannot use import statement outside a module",
  "trace": [
    "Runtime.UserCodeSyntaxError: SyntaxError: Cannot use import statement outside a module",
    "    at _loadUserApp (file:///var/runtime/index.mjs:1106:17)",
    "    at async UserFunction.js.module.exports.load (file:///var/runtime/index.mjs:1148:21)",
    "    at async start (file:///var/runtime/index.mjs:1332:23)",
    "    at async file:///var/runtime/index.mjs:1339:1"
  ]
}

Do you have any guidance on how I can isolate the error?

[seratch]

Thanks for your reply. It seems your settings allow only pure commonjs syntax and that's why your code does not work for those runtimes. I am not able to quickly guess what's the cause. Hope you'll figure the way to resolve it out soon.

[CharlieGreenman]

Thanks for your reply. It seems your settings allow only pure commonjs syntax and that's why your code does not work for those runtimes. I am not able to quickly guess what's the cause. Hope you'll figure the way to resolve it out soon.

I will add I am coming across this issue as well with AWS lambda (even though everything has been updated to node 22). I have spent quite sometime trying to debug and haven't solved yet(I have solved for jest config). Note, I did not have this issue when compiling locally using node 22 in our AI playground.

The recommended architecture with AWS lambda is to use a fat lambda(so all functions are running on the same runtime), and many packages needed are still on commonjs, and no way to isolate this agent as needs to talk internally to other commonjs functions via tool calling. OpenAI's agent would be the only ESM npm package in our very large nodejs backend repo. I do think interoperability for commonjs will be useful even for greenfield projects such as myself.

UPDATE:
I was looking through the AWS docs and I found the source of the issue. While nodejs22 will enable experimental esmodules by default AWS will not nor does AWS allow for it. Per documentation here https://aws.amazon.com/blogs/compute/node-js-22-runtime-now-available-in-aws-lambda/

Node.js 22 includes an experimental feature to detect the module syntax automatically (CommonJS or ES Modules). This feature must be enabled when the Node.js runtime is compiled. Since the Lambda-provided Node.js 22 runtime is intended for production workloads, this experimental feature is not enabled in the Lambda build and cannot be enabled via an execution-time flag. To use this feature in Lambda, you need to deploy your own Node.js runtime using a [custom runtime](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html) or [container image](https://docs.aws.amazon.com/lambda/latest/dg/python-image.html) with experimental module syntax detection enabled.

I suspect this is the source of the issue for AWS users. So in short, AWS users will not be able to use this without a custom nodejs runtime

Additional context/discussions re: AWS runtime: https://repost.aws/questions/QUybbyCc3EROmwOuU8qx6eog/experimental-require-module-not-being-respected-in-node22-x-lambda-runtime. So to confirm, there is no way AWS users using lambda can use this SDK

[CharlieGreenman]

Create a pull request here which hopefully will solve #258

Update:
I wasn't able to deploy so can't confirm it will work. My solution might quite possibly not solve. I know there are alot of packages making up the sum total, and a simple commonjs switch might not solve

Update Two:
I was able to solve and it works in prod for me now. I won't pass along here what I did, but if interested reach out(link in bio).

[github-actions]

This issue is stale because it has been open for 7 days with no activity.