chore: add docstrings

Author: dreamorosi

packages/event-handler/README.md

@@ -6,7 +6,7 @@ You can use the library in both TypeScript and JavaScript code bases.
 
 ## Intro
 
-Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Balancer (ALB), Lambda Function URLs, and VPC Lattice.
+Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Balancer (ALB), Lambda Function URLs, VPC Lattice, AWS AppSync Events APIs, and Amazon Bedrock Agent Functions.
 
 ## Usage
 
@@ -102,6 +102,8 @@ export const handler = async (event, context) =>
   app.resolve(event, context);
 ```
 
+## Bedrock Agent Functions
+
 See the [documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/event-handler/appsync-events) for more details on how to use the AppSync event handler.
 
 ## Contribute

packages/event-handler/src/bedrock-agent/BedrockAgentFunctionResolver.ts

@@ -169,6 +169,32 @@ export class BedrockAgentFunctionResolver {
     this.#logger.debug(`Tool "${name}" has been registered.`);
   }
 
+  /**
+   * Resolve an incoming Bedrock Agent function invocation event.
+   *
+   * @example
+   * ```ts
+   * import {
+   *   BedrockAgentFunctionResolver
+   * } from '@aws-lambda-powertools/event-handler/bedrock-agent';
+   *
+   * const app = new BedrockAgentFunctionResolver();
+   *
+   * app.tool(async (params) => {
+   *   const { name } = params;
+   *   return `Hello, ${name}!`;
+   * }, {
+   *   name: 'greeting',
+   *   description: 'Greets a person by name',
+   * });
+   *
+   * export const handler = async (event, context) =>
+   *   app.resolve(event, context);
+   * ```
+   *
+   * @param event - The incoming payload of the AWS Lambda function.
+   * @param context - The context object provided by AWS Lambda, which contains information about the invocation, function, and execution environment.
+   */
   async resolve(
     event: unknown,
     context: Context
@@ -181,19 +207,18 @@ export class BedrockAgentFunctionResolver {
       actionGroup,
       sessionAttributes,
       promptSessionAttributes,
-      // TODO: add knowledge bases
+      knowledgeBasesConfiguration,
     } = event;
 
     const tool = this.#tools.get(toolName);
 
     if (tool == null) {
       this.#logger.error(`Tool ${toolName} has not been registered.`);
       return new BedrockFunctionResponse({
-        actionGroup,
-        func: toolName,
         body: `Error: tool ${toolName} has not been registered.`,
         sessionAttributes,
         promptSessionAttributes,
+        knowledgeBasesConfiguration,
       }).build({
         actionGroup,
         func: toolName,
@@ -234,23 +259,21 @@ export class BedrockAgentFunctionResolver {
           ? ''
           : JSON.stringify(response);
       return new BedrockFunctionResponse({
-        actionGroup,
-        func: toolName,
         body,
         sessionAttributes,
         promptSessionAttributes,
+        knowledgeBasesConfiguration,
       }).build({
         actionGroup,
         func: toolName,
       });
     } catch (error) {
       this.#logger.error(`An error occurred in tool ${toolName}.`, error);
       return new BedrockFunctionResponse({
-        actionGroup,
-        func: toolName,
         body: `Unable to complete tool execution due to ${error instanceof Error ? `${error.name} - ${error.message}` : String(error)}`,
         sessionAttributes,
         promptSessionAttributes,
+        knowledgeBasesConfiguration,
       }).build({
         actionGroup,
         func: toolName,

packages/event-handler/src/bedrock-agent/BedrockFunctionResponse.ts

@@ -34,26 +34,30 @@ class BedrockFunctionResponse {
    * @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html#session-state-attributes | Bedrock Agent Session State Attributes} for more details.
    */
   readonly promptSessionAttributes: Record<string, string>;
+  /**
+   * Optional field to configure knowledge bases for the agent.
+   * @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html#session-state-kb | Bedrock Agent Knowledge Bases} for more details.
+   */
+  readonly knowledgeBasesConfiguration?: Record<string, unknown>;
 
   constructor({
-    actionGroup,
-    func,
     body,
     responseState = undefined,
     sessionAttributes = {},
     promptSessionAttributes = {},
+    knowledgeBasesConfiguration = {},
   }: {
-    actionGroup: string;
-    func: string;
     body: string;
     responseState?: 'FAILURE' | 'REPROMPT';
     sessionAttributes?: Record<string, string>;
     promptSessionAttributes?: Record<string, string>;
+    knowledgeBasesConfiguration?: Record<string, unknown>;
   }) {
     this.body = body;
     this.responseState = responseState;
     this.sessionAttributes = sessionAttributes;
     this.promptSessionAttributes = promptSessionAttributes;
+    this.knowledgeBasesConfiguration = knowledgeBasesConfiguration;
   }
 
   /**
@@ -87,6 +91,9 @@ class BedrockFunctionResponse {
       ...(this.promptSessionAttributes && {
         promptSessionAttributes: this.promptSessionAttributes,
       }),
+      ...(this.knowledgeBasesConfiguration && {
+        knowledgeBasesConfiguration: this.knowledgeBasesConfiguration,
+      }),
     };
   }
 }

packages/event-handler/src/types/bedrock-agent.ts

@@ -4,21 +4,45 @@ import type { BedrockAgentFunctionResolver } from '../bedrock-agent/BedrockAgent
 import type { BedrockFunctionResponse } from '../bedrock-agent/BedrockFunctionResponse.js';
 import type { GenericLogger } from '../types/common.js';
 
+/**
+ * Configuration for a tool in the Bedrock Agent Function Resolver.
+ */
 type Configuration = {
+  /**
+   * The name of the tool, which must be unique across all registered tools.
+   */
   name: string;
-  description: string;
+  /**
+   * A description of the tool, which is optional but highly recommended.
+   */
+  description?: string;
 };
 
+/**
+ * Parameter for a tool function in the Bedrock Agent Function Resolver.
+ * This is used to define the structure of parameters in tool functions.
+ */
 type Parameter = {
   name: string;
   type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
   value: string;
 };
 
+/**
+ * Primitive types that can be used as parameter values in tool functions.
+ * This is used to define the structure of parameters in tool functions.
+ */
 type ParameterPrimitives = string | number | boolean;
 
+/**
+ * Represents a value for a parameter, which can be a primitive type or an array of values.
+ * This is used to define the structure of parameters in tool functions.
+ */
 type ParameterValue = ParameterPrimitives | Array<ParameterValue>;
 
+/**
+ * Function to handle tool invocations in the Bedrock Agent Function Resolver.
+ */
 type ToolFunction<TParams = Record<string, ParameterValue>> = (
   params: TParams,
   options?: {
@@ -27,11 +51,21 @@ type ToolFunction<TParams = Record<string, ParameterValue>> = (
   }
 ) => Promise<JSONValue | BedrockFunctionResponse>;
 
+/**
+ * Tool in the Bedrock Agent Function Resolver.
+ *
+ * Used to register a tool in {@link BedrockAgentFunctionResolver | `BedrockAgentFunctionResolver`}.
+ */
 type Tool<TParams = Record<string, ParameterValue>> = {
   handler: ToolFunction<TParams>;
   config: Configuration;
 };
 
+/**
+ * Function invocation in the Bedrock Agent Function Resolver.
+ *
+ * This is used to define the structure of function invocations in tool functions.
+ */
 type FunctionInvocation = {
   actionGroup: string;
   function: string;
@@ -43,7 +77,28 @@ type FunctionInvocation = {
  *
  * @example
  * ```json
- *
+ * {
+ *   "messageVersion": "1.0",
+ *   "actionGroup": "exampleActionGroup",
+ *   "function": "getWeather",
+ *   "agent": {
+ *     "name": "WeatherAgent",
+ *     "id": "agent-id-123",
+ *     "alias": "v1",
+ *     "version": "1.0"
+ *   },
+ *   "parameters": [{
+ *     "name": "location",
+ *     "type": "string",
+ *     "value": "Seattle"
+ *   }],
+ *   "inputText": "What's the weather like in Seattle?",
+ *   "sessionId": "session-id-456",
+ *   "sessionAttributes": {
+ *     "userId": "user-789",
+ *   },
+ *   "promptSessionAttributes": {},
+ * }
  * ```
  */
 type BedrockAgentFunctionEvent = {
@@ -61,10 +116,19 @@ type BedrockAgentFunctionEvent = {
   sessionId: string;
   sessionAttributes: Record<string, string>;
   promptSessionAttributes: Record<string, string>;
+  knowledgeBasesConfiguration?: Record<string, unknown>;
 };
 
+/**
+ * Represents the state of the response from a Bedrock agent function:
+ * - `FAILURE`: The agent throws a `DependencyFailedException` for the current session.
+ * - `REPROMPT`: The agent passes a response string to the model to reprompt it.
+ */
 type ResponseState = 'FAILURE' | 'REPROMPT';
 
+/**
+ * Response structure for a Bedrock agent function.
+ */
 type BedrockAgentFunctionResponse = {
   messageVersion: string;
   response: {
@@ -84,7 +148,7 @@ type BedrockAgentFunctionResponse = {
 };
 
 /**
- * Options for the {@link BedrockAgentFunctionResolver} class
+ * Options for the {@link BedrockAgentFunctionResolver | `BedrockAgentFunctionResolver`} class
  */
 type ResolverOptions = {
   /**

packages/event-handler/src/types/index.ts

@@ -13,6 +13,7 @@ export type {
   BedrockAgentFunctionEvent,
   BedrockAgentFunctionResponse,
   ResolverOptions,
+  Parameter,
 } from './bedrock-agent.js';
 
 export type {

packages/event-handler/tests/unit/bedrock-agent/BedrockAgentFunctionResolver.test.ts

@@ -336,8 +336,6 @@ describe('Class: BedrockAgentFunctionResolver', () => {
     app.tool(
       async () => {
         return new BedrockFunctionResponse({
-          actionGroup: 'customActionGroup',
-          func: 'custom-response',
           body: 'I am not sure',
           responseState: 'REPROMPT',
           sessionAttributes: { customAttr: 'value' },

packages/event-handler/typedoc.json

@@ -4,6 +4,7 @@
   ],
   "entryPoints": [
     "./src/appsync-events/index.ts",
+    "./src/bedrock-agent/index.ts",
     "./src/types/index.ts",
   ],
   "readme": "README.md"