CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-langchain--aws

LangChain AWS integration providing chat models, embeddings, and retrievers for seamless AWS service connections.

Overview
Eval results
Files

authentication.mddocs/

Authentication & Configuration

Flexible authentication mechanisms and configuration options for AWS service integration, supporting multiple credential types, custom client configurations, and regional deployment patterns.

Capabilities

Credential Types

Core credential types supported across all @langchain/aws classes for AWS service authentication.

/**
 * AWS credential types supporting various authentication methods
 */
type CredentialType = AwsCredentialIdentity | Provider<AwsCredentialIdentity>;

interface AwsCredentialIdentity {
  /** AWS access key ID */
  accessKeyId: string;
  
  /** AWS secret access key */
  secretAccessKey: string;
  
  /** Optional session token for temporary credentials */
  sessionToken?: string;
  
  /** Optional expiration time for temporary credentials */
  expiration?: Date;
}

/**
 * Provider function for dynamic credential resolution
 */
type Provider<T> = () => Promise<T>;

Authentication Methods

1. Environment Variables

The most common authentication method using environment variables.

For Traditional AWS Credentials:

export BEDROCK_AWS_REGION="us-east-1"
export BEDROCK_AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export BEDROCK_AWS_ACCESS_KEY_ID="your-access-key-id"

# Alternative region setting
export AWS_DEFAULT_REGION="us-east-1"

For API Key Authentication:

export BEDROCK_AWS_REGION="us-east-1"
export AWS_BEARER_TOKEN_BEDROCK="your-bearer-token"

Usage Examples:

import { ChatBedrockConverse, BedrockEmbeddings } from "@langchain/aws";

// Automatically uses environment variables
const chatModel = new ChatBedrockConverse({
  region: process.env.BEDROCK_AWS_REGION ?? "us-east-1"
  // credentials will be automatically loaded from environment
});

const embeddings = new BedrockEmbeddings({
  region: process.env.BEDROCK_AWS_REGION ?? "us-east-1",
  model: "amazon.titan-embed-text-v1"
  // credentials automatically loaded
});

2. Direct Credential Configuration

Programmatically provide credentials for fine-grained control.

Usage Examples:

// Direct credential specification
const chatModel = new ChatBedrockConverse({
  region: "us-east-1",
  credentials: {
    accessKeyId: "AKIA...",
    secretAccessKey: "...",
    sessionToken: "..." // Optional for temporary credentials
  },
  model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
});

// Using credentials from external source
const dynamicCredentials = {
  accessKeyId: await getAccessKeyFromSecretManager(),
  secretAccessKey: await getSecretKeyFromSecretManager()
};

const embeddings = new BedrockEmbeddings({
  region: "us-west-2",
  credentials: dynamicCredentials,
  model: "amazon.titan-embed-text-v1"
});

3. AWS Profile-Based Authentication

Leverage AWS profiles for different environments and roles.

Usage Examples:

import { fromIni } from "@aws-sdk/credential-provider-ini";

// Use specific AWS profile
const profileCredentials = fromIni({ profile: "production" });

const chatModel = new ChatBedrockConverse({
  region: "us-east-1",
  credentials: profileCredentials,
  model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
});

// With profile-specific configuration
const stagingCredentials = fromIni({ 
  profile: "staging",
  filepath: "~/.aws/credentials",
  configFilepath: "~/.aws/config"
});

const stagingModel = new ChatBedrockConverse({
  region: "us-west-2",
  credentials: stagingCredentials
});

4. IAM Role Authentication

Use IAM roles for EC2 instances, ECS tasks, or Lambda functions.

Usage Examples:

import { fromInstanceMetadata } from "@aws-sdk/credential-provider-imds";
import { fromContainerMetadata } from "@aws-sdk/credential-provider-imds";

// For EC2 instances
const ec2Credentials = fromInstanceMetadata({
  timeout: 1000,
  maxRetries: 3
});

const ec2ChatModel = new ChatBedrockConverse({
  region: "us-east-1",
  credentials: ec2Credentials
});

// For ECS tasks
const ecsCredentials = fromContainerMetadata({
  timeout: 1000,
  maxRetries: 3
});

const ecsEmbeddings = new BedrockEmbeddings({
  region: "us-east-1",
  credentials: ecsCredentials,
  model: "amazon.titan-embed-text-v1"
});

5. AssumeRole Authentication

Assume IAM roles for cross-account access or enhanced security.

Usage Examples:

import { fromTemporaryCredentials } from "@aws-sdk/credential-provider-sts";

// Assume role with MFA
const assumeRoleCredentials = fromTemporaryCredentials({
  params: {
    RoleArn: "arn:aws:iam::123456789012:role/CrossAccountRole",
    RoleSessionName: "langchain-aws-session",
    SerialNumber: "arn:aws:iam::123456789012:mfa/user-name",
    TokenCode: "123456" // MFA token
  }
});

const crossAccountModel = new ChatBedrockConverse({
  region: "us-east-1",
  credentials: assumeRoleCredentials
});

// Assume role with external ID
const externalIdCredentials = fromTemporaryCredentials({
  params: {
    RoleArn: "arn:aws:iam::123456789012:role/ExternalRole",
    RoleSessionName: "external-session",
    ExternalId: "unique-external-id"
  }
});

6. Web Identity Token Authentication

Use OIDC identity providers for authentication (useful for GitHub Actions, etc.).

Usage Examples:

import { fromWebToken } from "@aws-sdk/credential-provider-web-identity";

// GitHub Actions OIDC
const githubCredentials = fromWebToken({
  roleArn: "arn:aws:iam::123456789012:role/GitHubActionsRole",
  webIdentityToken: process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN!,
  roleSessionName: "github-actions-session"
});

const cicdModel = new ChatBedrockConverse({
  region: "us-east-1",
  credentials: githubCredentials
});

Default Credential Provider Chain

The AWS SDK uses a credential provider chain that automatically tries multiple sources.

/**
 * Default credential provider chain configuration options
 */
interface DefaultProviderInit {
  /** AWS profile name to use */
  profile?: string;
  
  /** Path to credentials file */
  filepath?: string;
  
  /** Path to config file */
  configFilepath?: string;
  
  /** Whether to ignore credential cache */
  ignoreCache?: boolean;
  
  /** MFA code provider function */
  mfaCodeProvider?: (serialNumber: string) => Promise<string>;
  
  /** Role assumer function */
  roleAssumer?: (params: AssumeRoleParams) => Promise<Credentials>;
  
  /** Role ARN to assume */
  roleArn?: string;
  
  /** Web identity token file path */
  webIdentityTokenFile?: string;
  
  /** Role assumer with web identity */
  roleAssumerWithWebIdentity?: (params: AssumeRoleWithWebIdentityParams) => Promise<Credentials>;
}

Usage Examples:

// Let AWS SDK automatically discover credentials
const autoModel = new ChatBedrockConverse({
  region: "us-east-1"
  // No credentials specified - uses default provider chain:
  // 1. Environment variables
  // 2. AWS credentials file
  // 3. EC2/ECS instance metadata
  // 4. AWS SSO
});

// Customize default provider chain
const customChainModel = new ChatBedrockConverse({
  region: "us-east-1",
  profile: "production",
  ignoreCache: true,
  mfaCodeProvider: async (serialNumber) => {
    // Custom MFA code input logic
    return await promptUserForMFACode(serialNumber);
  }
});

Client Configuration

Advanced client configuration options for performance tuning and customization.

BedrockRuntimeClient Configuration

interface BedrockRuntimeClientConfig {
  /** AWS region */
  region?: string;
  
  /** Credentials provider */
  credentials?: CredentialType;
  
  /** Custom endpoint URL */
  endpoint?: string;
  
  /** Maximum retry attempts */
  maxAttempts?: number;
  
  /** Request handler for HTTP configuration */
  requestHandler?: RequestHandler;
  
  /** Custom user agent */
  customUserAgent?: string;
  
  /** Disable host prefix injection */
  disableHostPrefix?: boolean;
}

Usage Examples:

import { NodeHttpHandler } from "@aws-sdk/node-http-handler";
import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
import https from "https";

// Custom client configuration
const customClientConfig = {
  region: "us-east-1",
  maxAttempts: 5,
  requestHandler: new NodeHttpHandler({
    connectionTimeout: 10000,
    socketTimeout: 120000,
    httpAgent: new https.Agent({
      keepAlive: true,
      maxSockets: 50
    })
  })
};

// Use with ChatBedrockConverse
const chatModel = new ChatBedrockConverse({
  clientOptions: customClientConfig,
  model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
});

// Or provide custom client directly
const customClient = new BedrockRuntimeClient(customClientConfig);
const chatModelWithClient = new ChatBedrockConverse({
  client: customClient
});

Kendra and Knowledge Base Client Configuration

interface KendraClientConfig {
  region?: string;
  credentials?: CredentialType;
  endpoint?: string;
  maxAttempts?: number;
  requestHandler?: RequestHandler;
}

interface BedrockAgentRuntimeClientConfig {
  region?: string;
  credentials?: CredentialType;
  endpoint?: string;
  maxAttempts?: number;
  requestHandler?: RequestHandler;
}

Usage Examples:

// Kendra with custom client options
const kendraRetriever = new AmazonKendraRetriever({
  indexId: "your-index-id",
  topK: 10,
  region: "us-east-1",
  clientOptions: {
    maxAttempts: 3,
    requestHandler: new NodeHttpHandler({
      connectionTimeout: 5000,
      socketTimeout: 30000
    })
  }
});

// Knowledge Base with custom configuration
const kbRetriever = new AmazonKnowledgeBaseRetriever({
  knowledgeBaseId: "your-kb-id",
  topK: 5,
  region: "us-east-1",
  clientOptions: {
    maxAttempts: 3,
    requestHandler: new NodeHttpHandler({
      connectionTimeout: 8000,
      socketTimeout: 60000
    })
  }
});

Regional Configuration

Best practices for regional deployment and configuration.

Usage Examples:

// Multi-region configuration
const regions = ["us-east-1", "us-west-2", "eu-west-1"];

const multiRegionModels = regions.map(region => ({
  region,
  model: new ChatBedrockConverse({
    region,
    model: "anthropic.claude-3-5-sonnet-20240620-v1:0",
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
    }
  })
}));

// Smart region selection based on latency
async function selectOptimalRegion(testRegions: string[]): Promise<string> {
  const latencyTests = testRegions.map(async region => {
    const start = Date.now();
    try {
      const model = new ChatBedrockConverse({ region });
      await model.invoke([new HumanMessage("test")]);
      return { region, latency: Date.now() - start };
    } catch (error) {
      return { region, latency: Infinity };
    }
  });
  
  const results = await Promise.all(latencyTests);
  const optimal = results.reduce((best, current) => 
    current.latency < best.latency ? current : best
  );
  
  return optimal.region;
}

Error Handling and Debugging

Comprehensive error handling patterns for authentication and configuration issues.

Usage Examples:

async function createAuthenticatedModel(): Promise<ChatBedrockConverse> {
  try {
    const model = new ChatBedrockConverse({
      region: process.env.BEDROCK_AWS_REGION ?? "us-east-1",
      model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
    });
    
    // Test authentication with a simple call
    await model.invoke([new HumanMessage("test")]);
    return model;
    
  } catch (error) {
    if (error.name === "CredentialsProviderError") {
      console.error("Authentication failed - check AWS credentials");
      console.error("Ensure one of the following:");
      console.error("1. Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY");
      console.error("2. AWS credentials file: ~/.aws/credentials");
      console.error("3. IAM role for EC2/ECS instance");
      console.error("4. AWS SSO profile");
    } else if (error.name === "UnknownEndpoint") {
      console.error("Invalid region or service not available in region");
    } else if (error.name === "AccessDeniedException") {
      console.error("Access denied - check IAM permissions for Bedrock");
    } else {
      console.error("Model initialization failed:", error.message);
    }
    throw error;
  }
}

// Debug credential resolution
async function debugCredentials(): Promise<void> {
  const { defaultProvider } = await import("@aws-sdk/credential-provider-node");
  
  try {
    const credentialProvider = defaultProvider();
    const credentials = await credentialProvider();
    
    console.log("Credentials resolved successfully:");
    console.log("Access Key ID:", credentials.accessKeyId?.substring(0, 8) + "...");
    console.log("Has Secret Key:", !!credentials.secretAccessKey);
    console.log("Has Session Token:", !!credentials.sessionToken);
    console.log("Expiration:", credentials.expiration);
    
  } catch (error) {
    console.error("Credential resolution failed:", error.message);
    console.error("Check your AWS configuration:");
    console.error("- aws configure list");
    console.error("- aws sts get-caller-identity");
  }
}

Common AWS SDK Errors

Understanding and handling common error types that may occur when using @langchain/aws.

/**
 * Common AWS SDK error types and their meanings
 */
interface AWSErrorTypes {
  CredentialsProviderError: "Authentication credentials not found or invalid";
  UnknownEndpoint: "Invalid region or service not available in region";
  AccessDeniedException: "Insufficient IAM permissions for the requested operation";
  ThrottlingException: "Request rate limit exceeded, retry with exponential backoff";
  ResourceNotFoundException: "Requested AWS resource (index, knowledge base, etc.) not found";
  ValidationException: "Request parameters are invalid or malformed";
  ServiceException: "AWS service encountered an internal error";
}

Error Handling Examples:

import { ChatBedrockConverse } from "@langchain/aws";
import { HumanMessage } from "@langchain/core/messages";

async function robustChatModelUsage() {
  const model = new ChatBedrockConverse({
    region: "us-east-1",
    model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
  });

  try {
    const response = await model.invoke([
      new HumanMessage("Hello, world!")
    ]);
    return response.content;
    
  } catch (error: any) {
    switch (error.name) {
      case "CredentialsProviderError":
        console.error("Authentication failed - check AWS credentials");
        console.error("Solutions:");
        console.error("1. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY");
        console.error("2. Configure AWS CLI: aws configure");
        console.error("3. Use IAM roles for EC2/ECS instances");
        break;
        
      case "UnknownEndpoint":
        console.error("Invalid region or service not available");
        console.error("Check: region setting and Bedrock availability");
        break;
        
      case "AccessDeniedException":
        console.error("Insufficient permissions");
        console.error("Required IAM permissions:");
        console.error("- bedrock:InvokeModel");
        console.error("- bedrock:InvokeModelWithResponseStream");
        break;
        
      case "ThrottlingException":
        console.error("Rate limit exceeded - implement retry logic");
        // Implement exponential backoff
        await new Promise(resolve => setTimeout(resolve, 1000));
        // Retry the request
        break;
        
      case "ValidationException":
        console.error("Invalid request parameters:", error.message);
        break;
        
      case "ServiceException":
        console.error("AWS service error - retry may help:", error.message);
        break;
        
      default:
        console.error("Unexpected error:", error.message);
    }
    throw error;
  }
}

// Retry logic for transient errors
async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      const isRetryable = [
        "ThrottlingException",
        "ServiceException",
        "InternalFailureException"
      ].includes(error.name);
      
      if (!isRetryable || attempt === maxRetries) {
        throw error;
      }
      
      // Exponential backoff: 1s, 2s, 4s, etc.
      const delay = Math.pow(2, attempt - 1) * 1000;
      console.log(`Retry attempt ${attempt} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage with retry logic
const responseWithRetry = await withRetry(async () => {
  return await model.invoke([new HumanMessage("Hello!")]);
});

Security Best Practices

Guidelines for secure credential management and configuration.

Best Practices:

  1. Never hardcode credentials in source code
  2. Use least privilege IAM policies
  3. Rotate credentials regularly
  4. Use temporary credentials when possible
  5. Enable CloudTrail logging for API calls
  6. Use VPC endpoints for private communication

Usage Examples:

// Secure configuration patterns
class SecureAWSConfiguration {
  private static validateEnvironment(): void {
    const requiredVars = ["BEDROCK_AWS_REGION"];
    const missing = requiredVars.filter(v => !process.env[v]);
    
    if (missing.length > 0) {
      throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
    }
  }
  
  static createChatModel(): ChatBedrockConverse {
    this.validateEnvironment();
    
    return new ChatBedrockConverse({
      region: process.env.BEDROCK_AWS_REGION!,
      // Let AWS SDK handle credential resolution
      // Never put credentials in code
      model: "anthropic.claude-3-5-sonnet-20240620-v1:0",
      clientOptions: {
        // Use secure configurations
        maxAttempts: 3
      }
    });
  }
  
  static createEmbeddings(): BedrockEmbeddings {
    this.validateEnvironment();
    
    return new BedrockEmbeddings({
      region: process.env.BEDROCK_AWS_REGION!,
      model: "amazon.titan-embed-text-v1"
    });
  }
}

// Use in application
const secureModel = SecureAWSConfiguration.createChatModel();
const secureEmbeddings = SecureAWSConfiguration.createEmbeddings();

Configuration Examples by Environment

Development Environment

// Development with local AWS credentials
const devModel = new ChatBedrockConverse({
  region: "us-east-1",
  // Uses ~/.aws/credentials [default] profile
  model: "anthropic.claude-3-haiku-20240307-v1:0", // Cheaper model for dev
  temperature: 0.8,
  maxTokens: 500
});

Production Environment

// Production with IAM role
const prodModel = new ChatBedrockConverse({
  region: process.env.AWS_REGION!, // From environment
  model: "anthropic.claude-3-5-sonnet-20240620-v1:0",
  temperature: 0.3,
  maxTokens: 2000,
  clientOptions: {
    maxAttempts: 5,
    requestHandler: new NodeHttpHandler({
      connectionTimeout: 10000,
      socketTimeout: 120000
    })
  }
});

CI/CD Environment

// CI/CD with OIDC
const cicdModel = new ChatBedrockConverse({
  region: "us-east-1",
  credentials: fromWebToken({
    roleArn: process.env.AWS_ROLE_ARN!,
    webIdentityToken: process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN!,
    roleSessionName: "github-actions"
  }),
  model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
});

Install with Tessl CLI

npx tessl i tessl/npm-langchain--aws

docs

authentication.md

chat-models.md

embeddings.md

index.md

retrievers.md

tile.json