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
}

// ─────────────────────────────────────────────────────────────────────────────
// 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';

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

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.
  runtimeVersion?: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
  networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  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 7 @max 365 (days)
  strategies: MemoryStrategy[]; // @min 1, unique by type
  tags?: Record<string, 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
}