agentcore.ts

/* eslint-disable @typescript-eslint/no-unused-vars */
/**
 * READ-ONLY LLM CONTEXT - Do not edit this file.
 *
 * JSON File: agentcore/agentcore.json
 * Purpose: Top-level project configuration with flat resource model
 */

// ─────────────────────────────────────────────────────────────────────────────
// ROOT SCHEMA: AgentCoreProjectSpec
// ─────────────────────────────────────────────────────────────────────────────

interface AgentCoreProjectSpec {
  name: string; // @regex ^[A-Za-z][A-Za-z0-9]{0,22}$ @max 23 - project name
  version: number; // Schema version (integer)
  managedBy: 'CDK'; // Enum — infrastructure manager. Default: "CDK"
  tags?: Record<string, string>;
  runtimes: AgentEnvSpec[]; // Unique by name
  memories: Memory[]; // Unique by name
  credentials: Credential[]; // Unique by name
  evaluators: Evaluator[]; // Unique by name — custom evaluator definitions
  onlineEvalConfigs: OnlineEvalConfig[]; // Unique by name — online evaluation configs
  agentCoreGateways: AgentCoreGateway[]; // Unique by name — MCP gateways
  mcpRuntimeTools?: AgentCoreMcpRuntimeTool[]; // Unique by name — standalone MCP runtime tools (not behind a gateway)
  unassignedTargets?: AgentCoreGatewayTarget[]; // Unique by name — targets not yet assigned to a gateway
  policyEngines: PolicyEngine[]; // Unique by name — Cedar policy engines
  configBundles: ConfigBundle[]; // Unique by name — configuration bundles for versioned config
  abTests: ABTest[]; // Unique by name — A/B test experiments
  /** @internal Auto-managed by AB test creation. Do not configure directly. */
  httpGateways: HttpGateway[]; // Unique by name — HTTP gateways bound to a runtime
}

// ─────────────────────────────────────────────────────────────────────────────
// ENUMS
// ─────────────────────────────────────────────────────────────────────────────

type BuildType = 'CodeZip' | 'Container';
type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13' | 'PYTHON_3_14';
type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
type RuntimeVersion = PythonRuntime | NodeRuntime;
type NetworkMode = 'PUBLIC' | 'VPC';
interface NetworkConfig {
  subnets: string[]; // subnet-xxx IDs
  securityGroups: string[]; // sg-xxx IDs
}

type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE' | 'EPISODIC';
type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
type EvaluationLevel = 'SESSION' | 'TRACE' | 'TOOL_CALL';
type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel' | 'apiGateway' | 'lambdaFunctionArn';
type OutboundAuthType = 'OAUTH' | 'API_KEY' | 'NONE';
type GatewayAuthorizerType = 'NONE' | 'AWS_IAM' | 'CUSTOM_JWT';
type GatewayExceptionLevel = 'NONE' | 'DEBUG';
type PolicyEngineMode = 'LOG_ONLY' | 'ENFORCE';
type ValidationMode = 'FAIL_ON_ANY_FINDINGS' | 'IGNORE_ALL_FINDINGS';
type ComputeHost = 'Lambda' | 'AgentCoreRuntime';
type ABTestVariantName = 'C' | 'T1';

// ─────────────────────────────────────────────────────────────────────────────
// AGENT
// ─────────────────────────────────────────────────────────────────────────────

type ProtocolMode = 'HTTP' | 'MCP' | 'A2A' | 'AGUI';

interface AgentEnvSpec {
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
  build: BuildType;
  entrypoint: string; // @regex ^[a-zA-Z0-9_][a-zA-Z0-9_/.-]*\.(py|ts|js)(:[a-zA-Z_][a-zA-Z0-9_]*)?$ e.g. "main.py:handler" or "index.ts"
  codeLocation: string; // Directory path
  dockerfile?: string; // Custom Dockerfile name for Container builds (default: 'Dockerfile'). Must be a filename, not a path.
  buildContextPath?: string; // Docker build context directory for Container builds. Replaces codeLocation as the positional `docker build` argument.
  customDockerBuildArgs?: Record<string, string>; // Key/value pairs forwarded as --build-arg flags. Container builds only.
  runtimeVersion?: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
  networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  protocol?: ProtocolMode; // default 'HTTP'
  tags?: Record<string, string>;
}

interface Instrumentation {
  enableOtel: boolean; // default true - wrap entrypoint with opentelemetry-instrument
}

interface EnvVar {
  name: string; // @regex ^[A-Za-z_][A-Za-z0-9_]*$ @max 255
  value: string;
}

// ─────────────────────────────────────────────────────────────────────────────
// MEMORY
// ─────────────────────────────────────────────────────────────────────────────

interface Memory {
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
  eventExpiryDuration: number; // @min 3 @max 365 (days)
  strategies: MemoryStrategy[]; // Unique by type. Can be empty (short-term memory).
  tags?: Record<string, string>;
  encryptionKeyArn?: string;
  executionRoleArn?: string;
}

interface MemoryStrategy {
  type: MemoryStrategyType;
  name?: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
  description?: string;
  namespaces?: string[];
  reflectionNamespaces?: string[]; // EPISODIC only: namespaces for cross-episode reflections
}

// ─────────────────────────────────────────────────────────────────────────────
// CREDENTIAL
// ─────────────────────────────────────────────────────────────────────────────

interface Credential {
  authorizerType: 'ApiKeyCredentialProvider' | 'OAuthCredentialProvider';
  name: string; // @regex ^[a-zA-Z0-9\-_]+$ @min 1 @max 128
  // Additional fields for OAuthCredentialProvider:
  discoveryUrl?: string; // OIDC discovery URL (OAuth only)
  scopes?: string[]; // Supported scopes (OAuth only)
  vendor?: string; // Credential provider vendor type (OAuth only, default: 'CustomOauth2')
  managed?: boolean; // Whether auto-created by CLI (OAuth only)
  usage?: 'inbound' | 'outbound'; // Auth direction (OAuth only)
}

// ─────────────────────────────────────────────────────────────────────────────
// EVALUATOR
// ─────────────────────────────────────────────────────────────────────────────

interface Evaluator {
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
  level: EvaluationLevel;
  description?: string;
  config: EvaluatorConfig; // Must have either llmAsAJudge or codeBased, not both
  tags?: Record<string, string>;
}

interface EvaluatorConfig {
  llmAsAJudge?: LlmAsAJudgeConfig;
  codeBased?: CodeBasedConfig;
}

interface LlmAsAJudgeConfig {
  model: string; // Bedrock model ID or ARN
  instructions: string; // Evaluation instructions
  ratingScale: RatingScale; // Must have either numerical or categorical, not both
}

interface RatingScale {
  numerical?: { value: number; label: string; definition: string }[];
  categorical?: { label: string; definition: string }[];
}

interface CodeBasedConfig {
  managed?: ManagedCodeBasedConfig;
  external?: ExternalCodeBasedConfig;
}

interface ManagedCodeBasedConfig {
  codeLocation: string;
  entrypoint: string; // default 'lambda_function.handler'
  timeoutSeconds: number; // @min 1 @max 300 (default 60)
  additionalPolicies?: string[];
}

interface ExternalCodeBasedConfig {
  lambdaArn: string; // @regex ^arn:aws[a-z-]*:lambda:[a-z0-9-]+:\d{12}:function:.+$
}

// ─────────────────────────────────────────────────────────────────────────────
// ONLINE EVAL CONFIG
// ─────────────────────────────────────────────────────────────────────────────

interface OnlineEvalConfig {
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
  agent: string; // Agent name — must match a project agent
  evaluators: string[]; // @min 1 — evaluator names, Builtin.* IDs, or evaluator ARNs
  samplingRate: number; // @min 0.01 @max 100 (percentage)
  description?: string; // @max 200
  enableOnCreate?: boolean; // Whether to enable on create (default: true)
  tags?: Record<string, string>;
}

// ─────────────────────────────────────────────────────────────────────────────
// GATEWAY (MCP)
// ─────────────────────────────────────────────────────────────────────────────

interface AgentCoreGateway {
  name: string; // @regex ^[0-9a-zA-Z](?:[0-9a-zA-Z-]*[0-9a-zA-Z])?$ @max 100
  description?: string;
  targets: AgentCoreGatewayTarget[]; // Gateway targets
  authorizerType?: GatewayAuthorizerType; // default 'NONE'
  authorizerConfiguration?: AuthorizerConfig; // Required when authorizerType is 'CUSTOM_JWT'
  enableSemanticSearch?: boolean; // default true
  exceptionLevel?: GatewayExceptionLevel; // default 'NONE'
  policyEngineConfiguration?: GatewayPolicyEngineConfiguration;
  tags?: Record<string, string>;
}

interface AuthorizerConfig {
  customJwtAuthorizer?: {
    discoveryUrl: string; // OIDC discovery URL (HTTPS, must end with /.well-known/openid-configuration)
    allowedAudience?: string[];
    allowedClients?: string[];
    allowedScopes?: string[];
    customClaims?: CustomClaimValidation[];
  };
}

interface CustomClaimValidation {
  inboundTokenClaimName: string; // @regex ^[A-Za-z0-9_.:-]+$ @max 255
  inboundTokenClaimValueType: 'STRING' | 'STRING_ARRAY';
  authorizingClaimMatchValue: {
    claimMatchOperator: 'EQUALS' | 'CONTAINS' | 'CONTAINS_ANY';
    claimMatchValue: {
      matchValueString?: string; // @regex ^[A-Za-z0-9_.-]+$ @max 255
      matchValueStringList?: string[]; // each @regex ^[A-Za-z0-9_.-]+$ @max 255
    };
  };
}

interface GatewayPolicyEngineConfiguration {
  policyEngineName: string; // Reference to a PolicyEngine name
  mode: PolicyEngineMode;
}

// ─────────────────────────────────────────────────────────────────────────────
// GATEWAY TARGET
// ─────────────────────────────────────────────────────────────────────────────

interface AgentCoreGatewayTarget {
  name: string;
  targetType: GatewayTargetType;
  toolDefinitions?: ToolDefinition[]; // Required for 'lambda' targets
  compute?: ToolComputeConfig; // Required for 'lambda' and scaffold targets
  endpoint?: string; // URL — required for external 'mcpServer' targets
  outboundAuth?: OutboundAuth;
  apiGateway?: ApiGatewayConfig; // Required for 'apiGateway' target type
  schemaSource?: SchemaSource; // Required for 'openApiSchema' / 'smithyModel' targets
  lambdaFunctionArn?: LambdaFunctionArnConfig; // Required for 'lambdaFunctionArn' target type
}

interface OutboundAuth {
  type: OutboundAuthType; // default 'NONE'
  credentialName?: string; // Required when type is not 'NONE'
  scopes?: string[];
}

interface ToolDefinition {
  name: string;
  description?: string;
  inputSchema: object; // JSON Schema
  outputSchema?: object;
}

interface ToolComputeConfig {
  host: ComputeHost;
  implementation: ToolImplementationBinding;
  // Lambda-specific:
  nodeVersion?: NodeRuntime; // Required for TypeScript Lambda
  pythonVersion?: PythonRuntime; // Required for Python Lambda
  timeout?: number; // @min 1 @max 900
  memorySize?: number; // @min 128 @max 10240
  iamPolicy?: object; // IAM policy document
  // AgentCoreRuntime-specific:
  runtime?: RuntimeConfig;
}

interface ToolImplementationBinding {
  language: 'TypeScript' | 'Python';
  path: string;
  handler: string;
}

interface RuntimeConfig {
  artifact: 'CodeZip';
  pythonVersion: PythonRuntime;
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
  entrypoint: string; // Python file path with optional handler
  codeLocation: string;
  instrumentation?: Instrumentation;
  networkMode?: NetworkMode; // default 'PUBLIC'
  description?: string;
}

interface ApiGatewayConfig {
  restApiId: string;
  stage: string;
  apiGatewayToolConfiguration: {
    toolFilters: {
      filterPath: string;
      methods: ('GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS')[];
    }[];
    toolOverrides?: { name: string; path: string; method: string; description?: string }[];
  };
}

interface LambdaFunctionArnConfig {
  lambdaArn: string; // @max 170
  toolSchemaFile: string;
}

type SchemaSource = { inline: { path: string } } | { s3: { uri: string; bucketOwnerAccountId?: string } };

// ─────────────────────────────────────────────────────────────────────────────
// MCP RUNTIME TOOL
// ─────────────────────────────────────────────────────────────────────────────

interface AgentCoreMcpRuntimeTool {
  name: string;
  toolDefinition: ToolDefinition;
  compute: {
    host: 'AgentCoreRuntime'; // Only AgentCoreRuntime (Python only)
    implementation: ToolImplementationBinding;
    runtime?: RuntimeConfig;
    iamPolicy?: object;
  };
  bindings?: McpRuntimeBinding[]; // Grant agents permission to invoke this tool
}

interface McpRuntimeBinding {
  runtimeName: string; // Agent runtime name to bind to
  envVarName: string; // @regex ^[A-Za-z_][A-Za-z0-9_]*$ — env var for runtime ARN
}

// ─────────────────────────────────────────────────────────────────────────────
// POLICY ENGINE
// ─────────────────────────────────────────────────────────────────────────────

interface PolicyEngine {
  name: string; // @regex ^[A-Za-z][A-Za-z0-9_]{0,47}$ @max 48
  description?: string; // @max 4096
  encryptionKeyArn?: string;
  tags?: Record<string, string>;
  policies: Policy[]; // Unique by name
}

interface Policy {
  name: string; // @regex ^[A-Za-z][A-Za-z0-9_]{0,47}$ @max 48
  description?: string; // @max 4096
  statement: string; // Cedar policy statement
  sourceFile?: string;
  validationMode: ValidationMode; // default 'FAIL_ON_ANY_FINDINGS'
}

// ─────────────────────────────────────────────────────────────────────────────
// CONFIG BUNDLE
// ─────────────────────────────────────────────────────────────────────────────

interface ConfigBundle {
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,99}$ @max 100
  description?: string; // @max 500
  /** Component configurations keyed by component ARN or placeholder (e.g. {{runtime:<runtimeName>}}) */
  components: Record<string, ComponentConfiguration>;
  branchName?: string; // @max 128 — optional branch name for versioning
  commitMessage?: string; // @max 500 — optional commit message
}

interface ComponentConfiguration {
  configuration: Record<string, unknown>; // Freeform configuration for the component
}

// ─────────────────────────────────────────────────────────────────────────────
// AB TEST
// ─────────────────────────────────────────────────────────────────────────────

interface ABTest {
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
  description?: string; // @max 200
  gatewayRef: string; // Reference to the gateway (ARN or {{gateway:name}} placeholder)
  roleArn?: string;
  variants: [ABTestVariant, ABTestVariant]; // Exactly 2 — one 'C' (control) and one 'T1' (treatment). Weights must sum to 100.
  evaluationConfig: {
    onlineEvaluationConfigArn: string;
  };
  trafficAllocationConfig?: {
    routeOnHeader: { headerName: string };
  };
  maxDurationDays?: number; // @min 1 @max 90
  enableOnCreate?: boolean;
}

interface ABTestVariant {
  name: ABTestVariantName;
  weight: number; // @min 1 @max 100
  variantConfiguration: {
    configurationBundle: {
      bundleArn: string;
      bundleVersion: string;
    };
  };
}

// ─────────────────────────────────────────────────────────────────────────────
// HTTP GATEWAY
// ─────────────────────────────────────────────────────────────────────────────

/** @internal HTTP gateway auto-created when setting up an AB test. */
interface HttpGateway {
  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9-]{0,47}$ @max 48
  description?: string; // @max 200
  runtimeRef: string; // Reference to a runtime name from spec.runtimes
  roleArn?: string; // IAM role ARN — auto-created if omitted
}