AWS Lambda

import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import type { LambdaFunctionURLEvent } from "aws-lambda";
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";

// Created once per container, reused across warm invocations.
const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({ model: "openai/gpt-4o-mini" }),
  },
});

const copilotHandler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  cors: true,
});

function toFetchRequest(event: LambdaFunctionURLEvent): Request {
  const method = event.requestContext.http.method;
  const host = event.headers.host ?? "localhost";
  const query = event.rawQueryString ? `?${event.rawQueryString}` : "";

  const hasBody = method !== "GET" && method !== "HEAD" && event.body != null;

  return new Request(`https://${host}${event.rawPath}${query}`, {
    method,
    headers: new Headers(event.headers as Record<string, string>),
    body: hasBody
      ? event.isBase64Encoded
        ? Buffer.from(event.body!, "base64")
        : event.body
      : undefined,
  });
}

export const handler = awslambda.streamifyResponse(
  async (event: LambdaFunctionURLEvent, responseStream) => {
    const response = await copilotHandler(toFetchRequest(event));

    // Status and headers must be attached before the first byte is written.
    const stream = awslambda.HttpResponseStream.from(responseStream, {
      statusCode: response.status,
      headers: Object.fromEntries(response.headers),
    });

    if (!response.body) {
      stream.end();
      return;
    }

    // Readable.fromWeb bridges the Fetch ReadableStream to a Node stream, so
    // SSE chunks reach the client as the agent produces them.
    await pipeline(Readable.fromWeb(response.body as any), stream);
  },
);

import type { Writable } from "node:stream";

declare global {
  namespace awslambda {
    function streamifyResponse<TEvent>(
      handler: (event: TEvent, responseStream: Writable, context: unknown) => Promise<void>,
    ): (event: TEvent, responseStream: Writable, context: unknown) => Promise<void>;

    namespace HttpResponseStream {
      function from(
        stream: Writable,
        metadata: { statusCode: number; headers?: Record<string, string> },
      ): Writable;
    }
  }
}

export {};

aws lambda create-function-url-config \
  --function-name copilotkit-runtime \
  --auth-type NONE \
  --invoke-mode RESPONSE_STREAM \
  --cors '{"AllowOrigins":["https://myapp.com"],"AllowHeaders":["content-type","authorization"],"AllowMethods":["GET","POST"]}'

</Tab>
<Tab value="AWS SAM">
```yaml title="template.yaml"
Resources:
  CopilotKitRuntime:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./
      Handler: dist/handler.handler
      Runtime: nodejs22.x
      Timeout: 300
      MemorySize: 1024
      Environment:
        Variables:
          OPENAI_API_KEY: !Ref OpenAiApiKey
      FunctionUrlConfig:
        AuthType: NONE
        InvokeMode: RESPONSE_STREAM
        Cors:
          AllowOrigins: ["https://myapp.com"]
          AllowHeaders: ["content-type", "authorization"]
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        Target: node22
        Bundle: true
        EntryPoints: [src/handler.ts]

import type { APIGatewayProxyEvent } from "aws-lambda";

// REST proxy integrations deliver payload format 1.0: `httpMethod` and `path`
// rather than `requestContext.http.method` and `rawPath`. `path` excludes the
// stage name, which is what we want — it lines up with the runtime's basePath.
function toFetchRequest(event: APIGatewayProxyEvent): Request {
  const method = event.httpMethod;
  const headers = new Headers();
  for (const [name, value] of Object.entries(event.headers)) {
    if (value != null) headers.append(name, value);
  }

  const query = new URLSearchParams();
  for (const [name, values] of Object.entries(
    event.multiValueQueryStringParameters ?? {},
  )) {
    for (const value of values ?? []) query.append(name, value);
  }
  const search = query.toString();

  const hasBody = method !== "GET" && method !== "HEAD" && event.body != null;

  return new Request(
    `https://${headers.get("host") ?? "localhost"}${event.path}${search ? `?${search}` : ""}`,
    {
      method,
      headers,
      body: hasBody
        ? event.isBase64Encoded
          ? Buffer.from(event.body!, "base64")
          : event.body
        : undefined,
    },
  );
}

aws apigateway update-integration \
  --rest-api-id a1b2c3 \
  --resource-id aaa111 \
  --http-method ANY \
  --patch-operations '[
    {"op":"replace","path":"/uri","value":"arn:aws:apigateway:us-east-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-east-1:111122223333:function:copilotkit-runtime/response-streaming-invocations"},
    {"op":"replace","path":"/responseTransferMode","value":"STREAM"},
    {"op":"replace","path":"/timeoutInMillis","value":"900000"}
  ]'

aws apigateway create-deployment --rest-api-id a1b2c3 --stage-name prod

import { LambdaIntegration, ResponseTransferMode, RestApi, EndpointType } from "aws-cdk-lib/aws-apigateway";
import { Duration } from "aws-cdk-lib";

const api = new RestApi(this, "CopilotKitApi", {
  // Regional gets a 5-minute idle timeout; edge-optimized gets 30 seconds.
  endpointConfiguration: { types: [EndpointType.REGIONAL] },
});

api.root.addResource("api").addResource("copilotkit").addResource("{proxy+}").addMethod(
  "ANY",
  new LambdaIntegration(fn, {
    responseTransferMode: ResponseTransferMode.STREAM,
    timeout: Duration.minutes(15),
  }),
);

CopilotKitMethod:
  Type: AWS::ApiGateway::Method
  Properties:
    RestApiId: !Ref CopilotKitApi
    ResourceId: !Ref CopilotKitProxyResource
    HttpMethod: ANY
    AuthorizationType: NONE
    Integration:
      Type: AWS_PROXY
      IntegrationHttpMethod: POST
      ResponseTransferMode: STREAM
      TimeoutInMillis: 900000
      Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2021-11-15/functions/${CopilotKitRuntime.Arn}/response-streaming-invocations

npm install express serverless-http @copilotkit/runtime

import express from "express";
import serverlessHttp from "serverless-http";
import { CopilotRuntime, BuiltInAgent } from "@copilotkit/runtime/v2";
import { createCopilotExpressHandler } from "@copilotkit/runtime/v2/express";

const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({ model: "openai/gpt-4o-mini" }),
  },
});

const app = express();

app.use(
  createCopilotExpressHandler({
    runtime,
    basePath: "/api/copilotkit",
    cors: true,
  }),
);

export const handler = serverlessHttp(app);

createCopilotExpressHandler({
  runtime,
  basePath: "/api/copilotkit",
  mode: "single-route",
  cors: true,
});

const copilotHandler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  cors: true,
  hooks: {
    onRequest: async ({ request }) => {
      const token = request.headers.get("authorization");
      if (!token || !(await verifyToken(token))) {
        // Throwing a Response short-circuits the handler.
        throw new Response("Unauthorized", { status: 401 });
      }
    },
  },
});