AWS.LexV2 reference

Bot

Source: src/AWS/LexV2/Bot.ts

An Amazon Lex V2 conversational bot. The bot is the container for locales, intents, and slot types; conversations run against an alias of a built version.

Bot: Creating a Bot

Basic Bot

import * as AWS from "alchemy/AWS";

const role = yield* AWS.IAM.Role("BotRole", {
  assumeRolePolicyDocument: {
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { Service: "lexv2.amazonaws.com" },
        Action: ["sts:AssumeRole"],
      },
    ],
  },
});

const bot = yield* AWS.LexV2.Bot("OrderBot", {
  roleArn: role.roleArn,
});

Bot with Session and Privacy Settings

const bot = yield* AWS.LexV2.Bot("KidsBot", {
  roleArn: role.roleArn,
  dataPrivacy: { childDirected: true },
  idleSessionTTL: "10 minutes",
  description: "A bot for children",
});

Bot: Building the Conversation Graph

const locale = yield* AWS.LexV2.BotLocale("En", {
  botId: bot.botId,
  localeId: "en_US",
});
const intent = yield* AWS.LexV2.Intent("Greet", {
  botId: locale.botId,
  localeId: locale.localeId,
  sampleUtterances: ["hello", "hi"],
});
const version = yield* AWS.LexV2.BotVersion("V1", {
  botId: intent.botId,
  localeIds: [intent.localeId],
});
const alias = yield* AWS.LexV2.BotAlias("Live", {
  botId: version.botId,
  botVersion: version.botVersion,
});

BotAlias

Source: src/AWS/LexV2/BotAlias.ts

An alias of an Amazon Lex V2 bot — a stable pointer to a numbered bot version that runtime conversations (e.g. RecognizeText) target.

BotAlias: Creating an Alias

Alias on a Version

import * as AWS from "alchemy/AWS";

const alias = yield* AWS.LexV2.BotAlias("Live", {
  botId: version.botId,
  botVersion: version.botVersion,
});

Unassociated Alias

// point it at a version later without changing consumers
const alias = yield* AWS.LexV2.BotAlias("Staging", {
  botId: bot.botId,
});

BotAlias: Conversing at Runtime

const recognizeText = yield* AWS.LexV2.RecognizeText(alias);
const reply = yield* recognizeText({
  localeId: "en_US",
  sessionId: "user-123",
  text: "hello",
});

BotLocale

Source: src/AWS/LexV2/BotLocale.ts

A language/locale on the DRAFT version of an Amazon Lex V2 bot. Intents and slot types live under a locale; a locale must exist before either can be created.

BotLocale: Creating a Locale

US English Locale

import * as AWS from "alchemy/AWS";

const locale = yield* AWS.LexV2.BotLocale("En", {
  botId: bot.botId,
  localeId: "en_US",
});

Locale with Voice and Threshold

const locale = yield* AWS.LexV2.BotLocale("En", {
  botId: bot.botId,
  localeId: "en_US",
  nluIntentConfidenceThreshold: 0.7,
  voiceSettings: { voiceId: "Ivy", engine: "neural" },
});

BotVersion

Source: src/AWS/LexV2/BotVersion.ts

An immutable numbered version of an Amazon Lex V2 bot, snapshot from the DRAFT version. The provider builds each included locale first (if needed), so the version is immediately usable behind a BotAlias.

Versions are immutable: any prop change replaces the resource with a newly created version.

BotVersion: Creating a Version

import * as AWS from "alchemy/AWS";

const version = yield* AWS.LexV2.BotVersion("V1", {
  botId: intent.botId,
  // depend on the intent so the build includes it
  localeIds: [intent.localeId],
});
const alias = yield* AWS.LexV2.BotAlias("Live", {
  botId: version.botId,
  botVersion: version.botVersion,
});

CodeHookEventSource

Source: src/AWS/LexV2/CodeHookEventSource.ts

Event source connecting an Amazon Lex V2 bot alias’s Lambda code hook (dialog and fulfillment) to the hosting Lambda function.

At deploy time the implementation (LexV2.LambdaCodeHookEventSource) injects the function ARN into the alias’s botAliasLocaleSettings (through the alias’s binding contract) and creates the lambda:InvokeFunction Permission for lexv2.amazonaws.com; at runtime it dispatches matching code hook events to the handler and returns the handler’s response to Lex.

Enable the hook per intent with the dialogCodeHook / fulfillmentCodeHook props on LexV2.Intent.

Use the onCodeHook helper rather than the service directly, and provide LexV2.LambdaCodeHookEventSource on the hosting function.

CodeHookEventSource: Handling Code Hooks

export default BotFunction.make(
  { main: import.meta.url },
  Effect.gen(function* () {
    const alias = yield* AWS.LexV2.BotAlias("Live", {
      botId: version.botId,
      botVersion: version.botVersion,
    });

    // deploy: wires the alias's en_US code hook + invoke Permission
    // runtime: dispatches code hook events to this handler
    yield* AWS.LexV2.onCodeHook(alias, { localeId: "en_US" }, (event) =>
      Effect.succeed(
        AWS.LexV2.fulfillIntent(event, { message: "Order placed!" }),
      ),
    );

    return {};
  }).pipe(Effect.provide(AWS.LexV2.LambdaCodeHookEventSource)),
);

DeleteSession

Source: src/AWS/LexV2/DeleteSession.ts

Runtime binding for lex:DeleteSession — end a conversation with an Amazon Lex V2 bot alias, discarding its session state so the next user input starts a fresh conversation.

DeleteSession: Managing Sessions

// init
const deleteSession = yield* AWS.LexV2.DeleteSession(alias);

// runtime
yield* deleteSession({
  localeId: "en_US",
  sessionId: "user-123",
});

GetSession

Source: src/AWS/LexV2/GetSession.ts

Runtime binding for lex:GetSession — read the session state (active intent, slots, session attributes, interpretations) of a conversation with an Amazon Lex V2 bot alias.

GetSession: Managing Sessions

// init
const getSession = yield* AWS.LexV2.GetSession(alias);

// runtime
const session = yield* getSession({
  localeId: "en_US",
  sessionId: "user-123",
});
const intent = session.sessionState?.intent?.name;

Intent

Source: src/AWS/LexV2/Intent.ts

An intent on the DRAFT locale of an Amazon Lex V2 bot — an action the user wants to perform, recognized from sample utterances.

Intent: Creating Intents

Intent with Sample Utterances

import * as AWS from "alchemy/AWS";

const greet = yield* AWS.LexV2.Intent("Greet", {
  botId: locale.botId,
  localeId: locale.localeId,
  sampleUtterances: ["hello", "hi", "good morning"],
});

Built-in Parent Intent

const help = yield* AWS.LexV2.Intent("Help", {
  botId: locale.botId,
  localeId: locale.localeId,
  parentIntentSignature: "AMAZON.HelpIntent",
});

LambdaCodeHookEventSource

Source: src/AWS/LexV2/LambdaCodeHookEventSource.ts

Connects an Amazon Lex V2 bot alias’s Lambda code hook to the current Lambda function.

At deploy time this layer injects the function ARN into the alias’s botAliasLocaleSettings through the alias’s binding contract and materializes the lambda:InvokeFunction Permission for lexv2.amazonaws.com; at runtime it dispatches matching code hook events (matched on the bot id, alias id, and locale) to the registered handler and returns the handler’s response to Lex.

LambdaCodeHookEventSource: Handling Code Hooks

yield* LexV2.onCodeHook(alias, { localeId: "en_US" }, (event) =>
  Effect.succeed(LexV2.fulfillIntent(event, { message: "Done!" })),
);

PutSession

Source: src/AWS/LexV2/PutSession.ts

Runtime binding for lex:PutSession — create or overwrite the session state of a conversation with an Amazon Lex V2 bot alias, letting your application steer the dialog (e.g. pre-fill slots or elicit a specific intent).

PutSession: Managing Sessions

// init
const putSession = yield* AWS.LexV2.PutSession(alias);

// runtime
yield* putSession({
  localeId: "en_US",
  sessionId: "user-123",
  sessionState: {
    intent: { name: "OrderPizza", slots: {} },
    dialogAction: { type: "ElicitSlot", slotToElicit: "Size" },
  },
});

RecognizeText

Source: src/AWS/LexV2/RecognizeText.ts

Runtime binding for lex:RecognizeText — send user text to an Amazon Lex V2 bot alias and receive the interpreted intent and response messages.

The alias must point at a built bot version (see BotVersion).

RecognizeText: Conversing with a Bot

Recognize Text

// init
const recognizeText = yield* AWS.LexV2.RecognizeText(alias);

// runtime
const reply = yield* recognizeText({
  localeId: "en_US",
  sessionId: "user-123",
  text: "hello",
});
const intent = reply.sessionState?.intent?.name;

Wire into a Lambda Function

// Bind the alias in the init phase, call in the handler, and provide
// the RecognizeTextHttp layer on the Function's init Effect.
export default ChatFunction.make(
  { main: import.meta.url, functionUrl: true },
  Effect.gen(function* () {
    const alias = yield* AWS.LexV2.BotAlias("Live", {
      botId: version.botId,
      botVersion: version.botVersion,
    });
    const recognizeText = yield* AWS.LexV2.RecognizeText(alias);
    return {
      fetch: Effect.gen(function* () {
        const reply = yield* recognizeText({
          localeId: "en_US",
          sessionId: "user-123",
          text: "hello",
        });
        return HttpServerResponse.json({
          intent: reply.sessionState?.intent?.name ?? null,
        });
      }),
    };
  }).pipe(Effect.provide(AWS.LexV2.RecognizeTextHttp)),
);

RecognizeUtterance

Source: src/AWS/LexV2/RecognizeUtterance.ts

Runtime binding for lex:RecognizeUtterance — send user text or audio to an Amazon Lex V2 bot alias. Unlike RecognizeText, the response’s messages/sessionState/interpretations come back gzip-compressed and base64-encoded, and an audioStream reply is available for voice bots.

RecognizeUtterance: Conversing with a Bot

// init
const recognizeUtterance = yield* AWS.LexV2.RecognizeUtterance(alias);

// runtime — response fields are gzip+base64; decode before use
const reply = yield* recognizeUtterance({
  localeId: "en_US",
  sessionId: "user-123",
  requestContentType: "text/plain; charset=utf-8",
  inputStream: new TextEncoder().encode("hello"),
});

SlotType

Source: src/AWS/LexV2/SlotType.ts

A custom slot type on the DRAFT locale of an Amazon Lex V2 bot — the set of values a slot can take, with optional synonyms and resolution strategy.

SlotType: Creating Slot Types

import * as AWS from "alchemy/AWS";

const size = yield* AWS.LexV2.SlotType("Size", {
  botId: locale.botId,
  localeId: locale.localeId,
  slotTypeValues: [
    { value: "small", synonyms: ["tiny"] },
    { value: "large", synonyms: ["big", "huge"] },
  ],
  resolutionStrategy: "TopResolution",
});