Versions

Examples built with AgentCore CLI @aws/agentcore@0.26.0. Commands or flags may differ in other versions. Run agentcore --version to check yours.

Snapshot documentation

This page is a manually maintained snapshot written against @aws/agentcore@0.26.0. The agentcore.json schema evolves between CLI releases: fields may be added, renamed, or removed in later versions. For the authoritative, up-to-date schema, see the AgentCore CLI repository and its schema documentation. For official service documentation, see the Amazon Bedrock AgentCore Developer Guide.

agentcore.json Schema Reference

agentcore/agentcore.json is the declarative source of truth for all AgentCore resources in your project. When you run agentcore add, agentcore remove, or agentcore deploy, this file determines what to create, update, or remove.

Authoritative source for your installed version

After running agentcore create, your project has its own copy at agentcore/.llm-context/agentcore.ts with the exact types and validation rules for your installed CLI version. When in doubt, that file (and agentcore validate) is the ground truth for your current CLI.

File Location

your-project/
└── agentcore/
    ├── agentcore.json       ← this file
    ├── aws-targets.json     ← deployment account + region
    ├── .llm-context/        ← TypeScript type definitions (read-only reference)
    └── cdk/                 ← supplementary infrastructure

Top-Level Structure

{
  "name": "MyProject",
  "version": 1,
  "managedBy": "CDK",
  "tags": {},
  "runtimes": [],
  "memories": [],
  "credentials": [],
  "evaluators": [],
  "onlineEvalConfigs": [],
  "agentCoreGateways": [],
  "policyEngines": [],
  "configBundles": [],
  "abTests": [],
  "datasets": []
}

The root object always has name, version, and managedBy. Every resource type is a flat top-level array - there is no nesting between resources. Agents discover memories, credentials, and gateways at runtime via environment variables or SDK calls, not via references inside agentcore.json (with the exception of policyEngineConfiguration on gateways, and agent/runtimes references on evaluators and A/B tests).

Common mistake

The array of agent runtimes is called runtimes, not agents. This is the single most common typo when hand-editing this file.

runtimes

Defines the agent runtimes to deploy. Each entry corresponds to one AgentCore Runtime. See the AgentCore Runtime documentation for supported configurations.

{
  "runtimes": [
    {
      "name": "MyAgent",
      "build": "CodeZip",
      "entrypoint": "main.py",
      "codeLocation": "app/MyAgent/",
      "runtimeVersion": "PYTHON_3_13",
      "networkMode": "PUBLIC",
      "protocol": "HTTP"
    }
  ]
}

Runtime Fields

Field	Type	Required	Description
`name`	string	yes	Pattern: `^[a-zA-Z][a-zA-Z0-9_]{0,47}$`, max 48 chars
`build`	string	yes	`CodeZip` or `Container`
`entrypoint`	string	yes	Entry file, e.g. `main.py`. Optional handler suffix: `main.py:handler`
`codeLocation`	string	yes	Directory path relative to the project root
`dockerfile`	string	no	Custom Dockerfile name for `Container` builds (default: `Dockerfile`)
`runtimeVersion`	string	no	`PYTHON_3_10` – `PYTHON_3_14`, or `NODE_18` / `NODE_20` / `NODE_22`
`envVars`	array	no	List of `{name, value}` environment variables
`networkMode`	string	no	`PUBLIC` (default) or `VPC`
`networkConfig`	object	cond.	`{subnets: string[], securityGroups: string[]}`, required when `networkMode` is `VPC`
`instrumentation`	object	no	`{enableOtel: boolean}` - wraps the entrypoint with `opentelemetry-instrument` (default: `true`)
`protocol`	string	no	`HTTP` (default), `MCP`, `A2A`, or `AGUI`
`tags`	object	no	Key-value tags
`filesystemConfigurations`	array	no	Session storage, EFS, or S3 Files mounts (max 5 total)
`requestHeaderAllowlist`	array	no	Custom request headers to pass through to the agent beyond `Authorization` and `X-Amzn-Bedrock-AgentCore-Runtime-Custom-*` (max 20 headers); enforcement follows a blocklist at the service layer, aligned with Gateway's header propagation model

Build Types

Type	How It Works	Constraints
`CodeZip`	Python or Node source zipped and deployed directly to AgentCore Runtime	Max 250MB zipped / 750MB unzipped
`Container`	Docker image built in CodeBuild (ARM64), pushed to a per-agent ECR repository	Requires a `Dockerfile` in `codeLocation`

Protocol Details

Protocol	Description
`HTTP`	Standard HTTP agent endpoint (`/invocations`)
`MCP`	Agent exposed as a Model Context Protocol server
`A2A`	Agent-to-Agent protocol (Google A2A)
`AGUI`	Agent GUI protocol for interactive front-ends

Runtime Version

The CLI may scaffold runtimeVersion: "PYTHON_3_14" as the default. PYTHON_3_14 is a pre-release runtime. Use a stable version for production deployments:

"runtimeVersion": "PYTHON_3_13"

Valid values: PYTHON_3_10, PYTHON_3_11, PYTHON_3_12, PYTHON_3_13 (stable), PYTHON_3_14 (pre-release), NODE_18, NODE_20, NODE_22.

Always verify which runtimes are currently supported before deploying by checking the Amazon Bedrock AgentCore Developer Guide.

memories

Defines persistent memory resources for cross-session context. See the AgentCore Memory documentation for full details.

{
  "memories": [
    {
      "name": "SharedMemory",
      "eventExpiryDuration": 30,
      "strategies": [
        {
          "type": "SEMANTIC",
          "name": "semantic_strategy",
          "namespaceTemplates": ["users/{actorId}/facts"]
        },
        {
          "type": "SUMMARIZATION",
          "name": "summary_strategy"
        }
      ]
    }
  ]
}

Memory Fields

Field	Type	Required	Description
`name`	string	yes	Pattern: `^[a-zA-Z][a-zA-Z0-9_]{0,47}$`, max 48
`eventExpiryDuration`	integer	yes	Days before events expire (3–365)
`strategies`	array	no	Long-term memory extraction strategies (unique by type)
`tags`	object	no	Key-value tags
`encryptionKeyArn`	string	no	Customer-managed KMS key ARN
`executionRoleArn`	string	no	IAM role ARN for memory operations

Strategy Types

Type	Description	Key Fields
`SEMANTIC`	Extracts facts and knowledge as semantic vectors	`namespaceTemplates`
`SUMMARIZATION`	Creates conversation summaries	-
`USER_PREFERENCE`	Captures user preferences and settings	-
`EPISODIC`	Stores episodic memories with optional reflections	`namespaceTemplates`, `reflectionNamespaceTemplates`

Deprecated fields

namespaces and reflectionNamespaces are deprecated aliases for namespaceTemplates and reflectionNamespaceTemplates. Use the Templates variants in new configs.

Namespace Placeholders

Placeholder	Resolves To
`{actorId}`	The user/actor ID from the event
`{sessionId}`	The session ID
`{memoryStrategyId}`	The strategy's internal ID

credentials

Defines API key or OAuth credential providers stored in the AgentCore token vault. See the AgentCore Developer Guide for credential management details.

{
  "credentials": [
    {
      "authorizerType": "ApiKeyCredentialProvider",
      "name": "OpenAI"
    },
    {
      "authorizerType": "OAuthCredentialProvider",
      "name": "MyOAuthProvider",
      "discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
      "scopes": ["read", "write"],
      "usage": "outbound"
    }
  ]
}

Credential Fields

Field	Type	Required	Description
`authorizerType`	string	yes	`ApiKeyCredentialProvider` or `OAuthCredentialProvider`
`name`	string	yes	Pattern: `^[a-zA-Z0-9\-_]+$`, max 128 chars
`discoveryUrl`	string	OAuth	OIDC discovery URL
`scopes`	array	no	Supported OAuth scopes
`vendor`	string	no	OAuth vendor type (default: `CustomOauth2`)
`usage`	string	no	`inbound` or `outbound`

The actual secret value (API key or client secret) is never stored in agentcore.json - it lives in the AgentCore token vault (backed by AWS Secrets Manager), referenced only by name.

agentCoreGateways

Defines MCP gateways that federate tools for your agents. See the AgentCore Gateway documentation for full details.

{
  "agentCoreGateways": [
    {
      "name": "MyGateway",
      "description": "Gateway for agent tools",
      "authorizerType": "NONE",
      "enableSemanticSearch": true,
      "targets": [
        {
          "name": "WeatherTools",
          "targetType": "mcpServer",
          "endpoint": "https://mcp.example.com/mcp"
        },
        {
          "name": "MyLambdaTools",
          "targetType": "lambdaFunctionArn",
          "lambdaFunctionArn": {
            "lambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:my-func",
            "toolSchemaFile": "tool-schemas/my-func.json"
          }
        }
      ]
    }
  ]
}

Gateway Fields

Field	Type	Required	Description
`name`	string	yes	Pattern: `^[0-9a-zA-Z](?:[0-9a-zA-Z-]*[0-9a-zA-Z])?$`, max 100
`description`	string	no	Free-text description
`targets`	array	yes	List of tool targets exposed through this gateway
`authorizerType`	string	no	`NONE` (default), `AWS_IAM`, or `CUSTOM_JWT`
`authorizerConfiguration`	object	cond.	Required when `authorizerType` is `CUSTOM_JWT`
`enableSemanticSearch`	boolean	no	Default `true`
`exceptionLevel`	string	no	`NONE` (default) or `DEBUG`
`policyEngineConfiguration`	object	no	`{policyEngineName, mode}` - attaches a Cedar policy engine

Target Types

`targetType`	Key Config Field	Use Case
`mcpServer`	`endpoint`	Remote MCP server
`lambdaFunctionArn`	`lambdaFunctionArn` object	Lambda function with a tool schema file
`openApiSchema`	`schemaSource`	REST API described by OpenAPI
`smithyModel`	`schemaSource`	AWS service or Smithy-defined API
`apiGateway`	`apiGateway` object	API Gateway REST API

Tool Naming Convention

Tools exposed through a gateway are prefixed with the target name and a triple underscore:

${targetName}___${toolName}

For example, a target named WeatherTools with a tool get_forecast becomes WeatherTools___get_forecast in the agent's tool list.

policyEngines

Defines Cedar-based authorization for tool invocations. See the AgentCore Developer Guide for policy engine configuration details.

{
  "policyEngines": [
    {
      "name": "MyPolicyEngine",
      "description": "Authorization for production tools",
      "policies": [
        {
          "name": "AllowReadTools",
          "statement": "permit(principal, action == AgentCore::Action::\"WeatherTools___get_forecast\", resource is AgentCore::Gateway);",
          "validationMode": "FAIL_ON_ANY_FINDINGS"
        }
      ]
    }
  ]
}

Policy Engine Fields

Field	Type	Required	Description
`name`	string	yes	Pattern: `^[A-Za-z][A-Za-z0-9_]{0,47}$`, max 48. Immutable
`description`	string	no	Max 4096 chars
`encryptionKeyArn`	string	no	Customer-managed KMS key ARN
`policies`	array	no	Cedar policies managed by this engine (unique by name)

Policy Fields

Field	Type	Required	Description
`name`	string	yes	Pattern: `^[A-Za-z][A-Za-z0-9_]{0,47}$`, max 48. Immutable
`description`	string	no	Max 4096 chars
`statement`	string	cond.	Cedar policy text (35–10000 chars). Required unless `sourceFile` is set
`sourceFile`	string	cond.	Path to a `.cedar` file, relative to the project root
`validationMode`	string	no	`FAIL_ON_ANY_FINDINGS` (default) or `IGNORE_ALL_FINDINGS`

Cedar Policy Syntax Rules

Always constrain the resource:

// CORRECT — type constraint (for policies covering any action)
permit(principal, action, resource is AgentCore::Gateway);

// CORRECT — specific ARN (REQUIRED when targeting specific actions)
permit(
  principal,
  action == AgentCore::Action::"TargetName___tool_name",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway"
);

// WRONG — bare resource without type or ARN, fails at deploy
permit(principal, action, resource);

Resource specificity rule

When your policy specifies one or more specific actions (action == or action in [...]), you must use a specific Gateway ARN (resource == AgentCore::Gateway::"<arn>"). The type constraint (resource is AgentCore::Gateway) is only valid when matching any action.

Action names use the TargetName___tool_name format:

action == AgentCore::Action::"TargetName___tool_name"

Conditions can access invocation context:

when { context.input.priority == "HIGH" }

Policy Engine Modes (on a gateway)

Mode	Behavior
`LOG_ONLY`	Evaluates policies and logs decisions; does not block requests
`ENFORCE`	Actively allows or denies based on policy evaluation

tip

Always deploy in LOG_ONLY first, inspect CloudWatch logs to confirm correct behavior, then switch to ENFORCE.

Other Top-Level Arrays

These sections exist in the schema but are less commonly hand-edited; use agentcore add/agentcore status --type <type> to manage them:

Array	Purpose
`evaluators`	Custom LLM-as-judge or code-based evaluators
`onlineEvalConfigs`	Continuous evaluation pipelines bound to a runtime
`configBundles`	Versioned bundles of component configuration, used by A/B tests
`abTests`	A/B test experiments routing traffic between config bundle variants
`datasets`	Named datasets for Dataset Management
`harnesses`	Managed-harness agent definitions (no-code agent configuration)

Validation

After editing agentcore.json, always validate:

agentcore validate

This checks:

JSON syntax validity
Schema conformance (required fields, valid enum values, regex patterns)
Cross-references (memory names, policy engine names referenced by gateways)
That each runtime's codeLocation exists and contains the entrypoint file

Prints Valid on success.

Authoritative Sources

Topic	Source
Exact schema for your CLI version	`agentcore/.llm-context/agentcore.ts` in any project created with `agentcore create`
Runtime configuration	AgentCore Developer Guide
Memory strategies	AgentCore Memory docs
Gateway and targets	AgentCore Gateway docs
Cedar policy language	Cedar documentation
CLI command reference	`agentcore --help` and `agentcore <command> --help`

File Location​

Top-Level Structure​

runtimes​

Runtime Fields​

Build Types​

Protocol Details​

Runtime Version​

memories​

Memory Fields​

Strategy Types​

Namespace Placeholders​

credentials​

Credential Fields​

agentCoreGateways​

Gateway Fields​

Target Types​

Tool Naming Convention​

policyEngines​

Policy Engine Fields​

Policy Fields​

Cedar Policy Syntax Rules​

Policy Engine Modes (on a gateway)​

Other Top-Level Arrays​

Validation​

Authoritative Sources​