404 lines
19 KiB
TypeScript
404 lines
19 KiB
TypeScript
/* 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.
|
|
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
|
|
}
|