feat: add --request-header-allowlist CLI flag for agentcore add agent (#825) (#830)

Wire the existing requestHeaderAllowlist feature (already supported in the
TUI wizard and schema) into the non-interactive CLI path. Accepts
comma-separated header names that are auto-normalized with the
X-Amzn-Bedrock-AgentCore-Runtime-Custom- prefix.

- Add requestHeaderAllowlist field to CLI AddAgentOptions interface
- Register --request-header-allowlist option in AgentPrimitive.registerCommands()
- Add validation using existing validateHeaderAllowlist() utility
- Pass parsed headers through to both create and BYO agent paths

Author: aidandaly24

src/cli/commands/add/types.ts

@@ -33,6 +33,7 @@ export interface AddAgentOptions extends VpcOptions {
   customClaims?: string;
   clientId?: string;
   clientSecret?: string;
+  requestHeaderAllowlist?: string;
   idleTimeout?: number | string;
   maxLifetime?: number | string;
   json?: boolean;

src/cli/commands/add/validate.ts

@@ -16,6 +16,7 @@ import {
   matchEnumValue,
 } from '../../../schema';
 import { ARN_VALIDATION_MESSAGE, isValidArn } from '../shared/arn-utils';
+import { validateHeaderAllowlist } from '../shared/header-utils';
 import { parseAndValidateLifecycleOptions } from '../shared/lifecycle-utils';
 import { validateVpcOptions } from '../shared/vpc-utils';
 import { validateJwtAuthorizerOptions } from './auth-options';
@@ -252,6 +253,14 @@ export function validateAddAgentOptions(options: AddAgentOptions): ValidationRes
     }
   }
 
+  // Validate request header allowlist
+  if (options.requestHeaderAllowlist) {
+    const headerResult = validateHeaderAllowlist(options.requestHeaderAllowlist);
+    if (!headerResult.success) {
+      return { valid: false, error: headerResult.error };
+    }
+  }
+
   // Parse and validate lifecycle configuration
   const lifecycleResult = parseAndValidateLifecycleOptions(options);
   if (!lifecycleResult.valid) return lifecycleResult;

src/cli/primitives/AgentPrimitive.tsx

@@ -15,6 +15,7 @@ import type {
 import { AgentEnvSpecSchema, CREDENTIAL_PROVIDERS, LIFECYCLE_TIMEOUT_MAX, LIFECYCLE_TIMEOUT_MIN } from '../../schema';
 import type { AddAgentOptions as CLIAddAgentOptions } from '../commands/add/types';
 import { validateAddAgentOptions } from '../commands/add/validate';
+import { parseAndNormalizeHeaders } from '../commands/shared/header-utils';
 import type { VpcOptions } from '../commands/shared/vpc-utils';
 import { VPC_ENDPOINT_WARNING, parseCommaSeparatedList } from '../commands/shared/vpc-utils';
 import { getErrorMessage } from '../errors';
@@ -51,6 +52,7 @@ export interface AddAgentOptions extends VpcOptions {
   apiKey?: string;
   memory?: MemoryOption;
   protocol?: ProtocolMode;
+  requestHeaderAllowlist?: string[];
   codeLocation?: string;
   entrypoint?: string;
   bedrockAgentId?: string;
@@ -106,7 +108,10 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
       const project = await configIO.readProjectSpec();
       const existingAgent = project.runtimes.find(agent => agent.name === options.name);
       if (existingAgent) {
-        return { success: false, error: `Agent "${options.name}" already exists in this project.` };
+        return {
+          success: false,
+          error: `Agent "${options.name}" already exists. To update its configuration, edit agentcore/agentcore.json directly.`,
+        };
       }
 
       if (options.type === 'import') {
@@ -224,6 +229,10 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
       .option('--custom-claims <json>', 'Custom claim validations as JSON array (for CUSTOM_JWT) [non-interactive]')
       .option('--client-id <id>', 'OAuth client ID for agent bearer token [non-interactive]')
       .option('--client-secret <secret>', 'OAuth client secret [non-interactive]')
+      .option(
+        '--request-header-allowlist <headers>',
+        'Comma-separated list of custom header names to allow (auto-prefixed with X-Amzn-Bedrock-AgentCore-Runtime-Custom-) [non-interactive]'
+      )
       .option(
         '--idle-timeout <seconds>',
         `Idle session timeout in seconds (${LIFECYCLE_TIMEOUT_MIN}-${LIFECYCLE_TIMEOUT_MAX}) [non-interactive]`
@@ -258,6 +267,11 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
             ? (JSON.parse(cliOptions.customClaims) as CustomClaimValidation[])
             : undefined;
 
+          // Parse request header allowlist if provided
+          const requestHeaderAllowlist = cliOptions.requestHeaderAllowlist
+            ? parseAndNormalizeHeaders(cliOptions.requestHeaderAllowlist)
+            : undefined;
+
           const result = await this.add({
             name: cliOptions.name!,
             type: cliOptions.type ?? 'create',
@@ -271,6 +285,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
             networkMode: cliOptions.networkMode,
             subnets: cliOptions.subnets,
             securityGroups: cliOptions.securityGroups,
+            requestHeaderAllowlist,
             codeLocation: cliOptions.codeLocation,
             entrypoint: cliOptions.entrypoint,
             bedrockAgentId: cliOptions.agentId,
@@ -378,6 +393,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
             customClaims: options.customClaims,
           },
         }),
+      requestHeaderAllowlist: options.requestHeaderAllowlist,
       idleRuntimeSessionTimeout: options.idleTimeout,
       maxLifetime: options.maxLifetime,
     };
@@ -520,6 +536,9 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
         }),
       // MCP uses mcp.run() which is incompatible with the opentelemetry-instrument wrapper
       ...(protocol === 'MCP' && { instrumentation: { enableOtel: false } }),
+      ...(options.requestHeaderAllowlist?.length && {
+        requestHeaderAllowlist: options.requestHeaderAllowlist,
+      }),
       ...(authorizerType && { authorizerType }),
       ...(authorizerConfiguration && { authorizerConfiguration }),
       ...(lifecycleConfiguration && { lifecycleConfiguration }),