Configuration Reference

AgentCore projects use JSON configuration files in the agentcore/ directory.

Files Overview

File	Purpose
agentcore.json	Project, agents, memories, credentials, evaluators, online evals, gateways
aws-targets.json	Deployment targets
.cli/deployed-state.json	Runtime state (auto-managed, do not edit)
.env.local	API keys for local development (gitignored)

---

agentcore.json

Main project configuration using a flat resource model. Agents, memories, and credentials are top-level arrays.

{
  "name": "MyProject",
  "version": 1,
  "tags": {
    "agentcore:created-by": "agentcore-cli",
    "agentcore:project-name": "MyProject"
  },
  "runtimes": [
    {
      "name": "MyAgent",
      "build": "CodeZip",
      "entrypoint": "main.py",
      "codeLocation": "app/MyAgent/",
      "runtimeVersion": "PYTHON_3_14",
      "networkMode": "PUBLIC",
      "protocol": "HTTP"
    }
  ],
  "memories": [],
  "credentials": [],
  "payments": [],
  "evaluators": [],
  "onlineEvalConfigs": [],
  "agentCoreGateways": [],
  "policyEngines": []
}

Project Fields

Field	Required	Description
name	Yes	Project name (1-23 chars, alphanumeric, starts with letter)
version	Yes	Schema version (integer, currently 1)
tags	No	Project-level tags applied to all resources
runtimes	Yes	Array of agent specifications
memories	Yes	Array of memory resources
credentials	Yes	Array of credential providers (API key or OAuth)
evaluators	Yes	Array of custom evaluator definitions
onlineEvalConfigs	Yes	Array of online eval configurations
payments	No	Array of payment manager configurations
policyEngines	No	Array of policy engine configurations
agentCoreGateways	No	Array of gateway definitions
mcpRuntimeTools	No	Array of MCP runtime tool definitions
unassignedTargets	No	Targets not yet assigned to a gateway

Gateway configuration is in the agentCoreGateways field. See Gateways and MCP Tools below.

---

Tags

AgentCore projects support config-driven tagging at both the project and resource levels. Tags flow through to the deployed CloudFormation resources and help with resource organization, cost allocation, and automation.

Project-Level Tags

Project-level tags are defined at the root of agentcore.json and are applied to all deployed resources. When you initialize a new project, two default tags are automatically created:

• agentcore:created-by — set to "agentcore-cli"
• agentcore:project-name — set to your project name

You can add additional project-level tags by editing the tags field in agentcore.json:

{
  "name": "MyProject",
  "version": 1,
  "tags": {
    "agentcore:created-by": "agentcore-cli",
    "agentcore:project-name": "MyProject",
    "Environment": "production",
    "Team": "platform",
    "CostCenter": "engineering"
  },
  "runtimes": [...],
  "memories": [...]
}

Per-Resource Tags

Individual resources can define their own tags. When a resource-level tag uses the same key as a project-level tag, the resource-level value takes precedence for that specific resource.

Example:

{
  "name": "MyProject",
  "version": 1,
  "tags": {
    "Environment": "production",
    "Team": "platform"
  },
  "runtimes": [
    {
      "name": "MyAgent",
      "tags": {
        "Environment": "staging",
        "Owner": "alice"
      },
      ...
    }
  ]
}

In this example, MyAgent will have tags: Environment: staging (overrides project-level), Team: platform (inherited from project), and Owner: alice (resource-specific).

Taggable Resources

The following resource types support tags:

• Agents (runtimes array in agentcore.json)
• Memories (memories array in agentcore.json)
• Gateways (agentCoreGateways array in agentcore.json)
• Evaluators (evaluators array in agentcore.json)
• Online Eval Configs (onlineEvalConfigs array in agentcore.json)
• Policy Engines (policyEngines array in agentcore.json)

Resources that are not taggable include credentials, MCP runtime tools, unassigned targets, and policies.

Tag Constraints

Tags must follow AWS tagging requirements:

• Keys: 1-128 characters, cannot start with aws:, allowed characters are Unicode letters, digits, whitespace, and _.:/=+-@
• Values: 0-256 characters, same allowed characters as keys
• Maximum: 50 tags per resource

Managing Tags

Tags are managed by editing agentcore.json directly. There are no CLI commands for tag management. Changes take effect on the next deployment.

---

Agent Specification (AgentEnvSpec)

{
  "name": "MyAgent",
  "build": "CodeZip",
  "entrypoint": "main.py",
  "codeLocation": "app/MyAgent/",
  "runtimeVersion": "PYTHON_3_14",
  "networkMode": "PUBLIC",
  "envVars": [{ "name": "MY_VAR", "value": "my-value" }],
  "instrumentation": {
    "enableOtel": true
  }
}

Field	Required	Description
name	Yes	Agent name (1-48 chars, alphanumeric + underscore)
build	Yes	"CodeZip" or "Container"
entrypoint	Yes	Entry file (e.g., main.py or main.py:handler)
codeLocation	Yes	Directory containing agent code (and the Dockerfile for Container builds)
runtimeVersion	Yes	Runtime version (see below)
networkMode	No	"PUBLIC" (default) or "VPC"
networkConfig	No	VPC configuration (subnets, security groups)
protocol	No	"HTTP" (default), "MCP", or "A2A"
envVars	No	Custom environment variables
instrumentation	No	OpenTelemetry settings
authorizerType	No	"AWS_IAM" or "CUSTOM_JWT"
authorizerConfiguration	No	JWT authorizer settings (for CUSTOM_JWT)
requestHeaderAllowlist	No	Headers to forward to the agent
lifecycleConfiguration	No	Runtime session lifecycle settings (idle timeout, max lifetime)
executionRoleArn	No	ARN of an existing IAM execution role (skips CDK-managed role)
tags	No	Agent-level tags
buildContextPath	No	Container only. Docker build context directory (replaces codeLocation as context).
customDockerBuildArgs	No	Container only. Key/value pairs forwarded as --build-arg flags.

Runtime Versions

Python:

• PYTHON_3_10
• PYTHON_3_11
• PYTHON_3_12
• PYTHON_3_13
• PYTHON_3_14

Node.js:

• NODE_18
• NODE_20
• NODE_22

---

Memory Resource

{
  "name": "MyMemory",
  "eventExpiryDuration": 30,
  "strategies": [{ "type": "SEMANTIC" }, { "type": "SUMMARIZATION" }]
}

Field	Required	Description
name	Yes	Memory name (1-48 chars)
eventExpiryDuration	Yes	Days until events expire (7-365)
strategies	Yes	Array of memory strategies (can be empty for short-term memory)

Memory Strategies

Strategy	Description
SEMANTIC	Vector-based similarity search for relevant context
SUMMARIZATION	Compressed conversation history
USER_PREFERENCE	Store user-specific preferences and settings
EPISODIC	Capture and reflect on meaningful interaction episodes

Strategy configuration:

{
  "type": "SEMANTIC",
  "name": "custom_semantic",
  "description": "Custom semantic memory",
  "namespaceTemplates": ["/users/facts", "/users/preferences"]
}

---

Credential Resource

API Key Credential

{
  "authorizerType": "ApiKeyCredentialProvider",
  "name": "OpenAI"
}

Field	Required	Description
authorizerType	Yes	Always "ApiKeyCredentialProvider"
name	Yes	Credential name (1-128 chars)

OAuth Credential

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

Field	Required	Description
authorizerType	Yes	Always "OAuthCredentialProvider"
name	Yes	Credential name (1-128 chars)
discoveryUrl	Yes	OIDC discovery URL (must be a valid URL)
scopes	No	Array of OAuth scopes
vendor	No	Credential provider vendor (default: "CustomOauth2")
managed	No	Whether auto-created by the CLI (do not edit)
usage	No	"inbound" or "outbound"

The actual secrets (API keys, client IDs, client secrets) are stored in .env.local for local development and in AgentCore Identity service for deployed environments.

---

Evaluator Resource

See Evaluations for the full guide.

{
  "name": "ResponseQuality",
  "level": "SESSION",
  "description": "Evaluate response quality",
  "config": {
    "llmAsAJudge": {
      "model": "us.anthropic.claude-sonnet-4-5-20250514-v1:0",
      "instructions": "Evaluate the response quality. Context: {context}",
      "ratingScale": {
        "numerical": [
          { "value": 1, "label": "Poor", "definition": "Fails to meet expectations" },
          { "value": 5, "label": "Excellent", "definition": "Far exceeds expectations" }
        ]
      }
    }
  }
}

Field	Required	Description
name	Yes	Evaluator name (1-48 chars, alphanumeric + _)
level	Yes	"SESSION", "TRACE", or "TOOL_CALL"
description	No	Evaluator description
config	Yes	LLM-as-a-Judge configuration (see below)

LLM-as-a-Judge Config

Field	Required	Description
model	Yes	Bedrock model ID or cross-region inference profile
instructions	Yes	Evaluation prompt with placeholders (e.g. {context})
ratingScale	Yes	Either numerical or categorical array (not both)

Rating Scale

Numerical — scored values:

{ "numerical": [{ "value": 1, "label": "Poor", "definition": "..." }, ...] }

Categorical — named labels:

{ "categorical": [{ "label": "Pass", "definition": "..." }, ...] }

---

Online Eval Config Resource

{
  "name": "QualityMonitor",
  "agent": "MyAgent",
  "evaluators": ["ResponseQuality", "Builtin.Faithfulness"],
  "samplingRate": 10,
  "enableOnCreate": true
}

Field	Required	Description
name	Yes	Config name (1-48 chars, alphanumeric + _)
agent	Yes	Agent name to monitor (must match a project agent)
evaluators	Yes	Array of evaluator names, Builtin.* IDs, or evaluator ARNs
samplingRate	Yes	Percentage of requests to evaluate (0.01–100)
description	No	Config description (max 200 chars)
enableOnCreate	No	Enable evaluation on deploy (default: true)

---

Gateways and MCP Tools

Gateway and MCP tool configuration is part of agentcore.json (in the agentCoreGateways, mcpRuntimeTools, and unassignedTargets fields).

{
  "name": "MyProject",
  "version": 1,
  "runtimes": [...],
  "agentCoreGateways": [
    {
      "name": "MyGateway",
      "description": "My gateway",
      "authorizerType": "NONE",
      "targets": [
        {
          "name": "WeatherTools",
          "targetType": "mcpServer",
          "endpoint": "https://mcp.example.com/mcp"
        }
      ]
    }
  ]
}

Gateway

Field	Required	Description
name	Yes	Gateway name (alphanumeric, hyphens, 1-100 chars)
description	No	Gateway description
targets	Yes	Array of gateway targets
authorizerType	No	"NONE" (default), "AWS_IAM", or "CUSTOM_JWT"
authorizerConfiguration	No	Required when authorizerType is "CUSTOM_JWT" (see below)

CUSTOM_JWT Authorizer Configuration

{
  "authorizerType": "CUSTOM_JWT",
  "authorizerConfiguration": {
    "customJwtAuthorizer": {
      "discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
      "allowedAudience": ["my-api"],
      "allowedClients": ["my-client-id"],
      "allowedScopes": ["read", "write"]
    }
  }
}

Field	Required	Description
discoveryUrl	Yes	OIDC discovery URL (must end with /.well-known/openid-configuration)
allowedAudience	Cond.	Array of allowed audience values
allowedClients	Cond.	Array of allowed client IDs
allowedScopes	Cond.	Array of allowed scopes
customClaims	Cond.	Custom claims for JWT validation

At least one of allowedAudience, allowedClients, allowedScopes, or customClaims must be provided.

Gateway Target

A target is a backend tool exposed through a gateway. Targets can be external MCP server endpoints or compute-backed implementations.

External MCP server endpoint:

{
  "name": "WeatherTools",
  "targetType": "mcpServer",
  "endpoint": "https://mcp.example.com/mcp"
}

External endpoint with outbound auth:

{
  "name": "SecureTools",
  "targetType": "mcpServer",
  "endpoint": "https://api.example.com/mcp",
  "outboundAuth": {
    "type": "OAUTH",
    "credentialName": "MyOAuthProvider",
    "scopes": ["tools:read"]
  }
}

Field	Required	Description
name	Yes	Target name
targetType	Yes	"mcpServer", "lambda", "openApiSchema", "smithyModel", "apiGateway", or "lambdaFunctionArn"
endpoint	Cond.	MCP server URL (required for external mcpServer targets)
compute	Cond.	Compute configuration (required for lambda and scaffolded targets)
toolDefinitions	Cond.	Array of tool definitions (required for lambda targets)
outboundAuth	No	Outbound authentication configuration

Outbound Auth

Field	Required	Description
type	Yes	"OAUTH", "API_KEY", or "NONE" (default)
credentialName	Cond.	Credential name (required when type is not "NONE")
scopes	No	OAuth scopes (for "OAUTH" type)

---

Payment Manager Resource

Payment managers define how agents handle x402 microtransactions. Each manager has one or more connectors that provide wallet credentials. See Payments for the full usage guide.

{
  "payments": [
    {
      "name": "MyManager",
      "authorizerType": "AWS_IAM",
      "autoPayment": true,
      "defaultSpendLimit": "10.00",
      "paymentToolAllowlist": ["web_search", "fetch_url"],
      "networkPreferences": ["eip155:84532"],
      "description": "Production payment manager",
      "connectors": [
        {
          "name": "MyCDPConnector",
          "provider": "CoinbaseCDP",
          "credentialName": "my-cdp-creds"
        }
      ]
    }
  ]
}

Payment Manager Fields

Field	Required	Description
name	Yes	Manager name (alphanumeric + underscore, max 48, starts with letter)
authorizerType	No	"AWS_IAM" (default) or "CUSTOM_JWT"
authorizerConfiguration	Cond.	Required when authorizerType is "CUSTOM_JWT" (see below)
connectors	Yes	Array of payment connector objects
autoPayment	No	Enable automatic payment (default: true)
defaultSpendLimit	No	Spend cap (USD) for invoke --auto-session sessions only; not a deployed-agent budget (e.g., "10.00")
paymentToolAllowlist	No	Array of tool names eligible for payment
networkPreferences	No	Array of network identifiers (e.g., "eip155:84532")
description	No	Human-readable description

Authorizer Configuration (CUSTOM_JWT)

{
  "authorizerConfiguration": {
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/.well-known/openid-configuration",
      "allowedClients": ["client-id-1"],
      "allowedAudience": ["https://api.example.com"],
      "allowedScopes": ["payments:read", "payments:write"]
    }
  }
}

Field	Required	Description
discoveryUrl	Yes	OIDC discovery URL
allowedClients	No	Array of allowed client IDs
allowedAudience	No	Array of allowed audiences
allowedScopes	No	Array of allowed scopes

Payment Connector

Field	Required	Description
name	Yes	Connector name (alphanumeric + underscore, max 48)
provider	No	"CoinbaseCDP" (default) or "StripePrivy"
credentialName	Yes	Name of the credential (maps to .env.local vars)

Payment Credential Provider

Payment connectors use a PaymentCredentialProvider credential type, distinct from ApiKeyCredentialProvider and OAuthCredentialProvider. The credential is automatically created during agentcore deploy from values in .env.local. You do not need to add it to the credentials array manually.

---

aws-targets.json

Deployment target

[
  {
    "name": "default",
    "description": "Production (us-west-2)",
    "account": "123456789012",
    "region": "us-west-2"
  }
]

Field	Required	Description
name	Yes	Target name (used with --target flag)
description	No	Target description
account	Yes	AWS account ID (12 digits)
region	Yes	AWS region

Supported Regions

See AgentCore Regions for the current list.

---

.env.local

Secrets for local development. This file is gitignored.

# API key credentials
AGENTCORE_CREDENTIAL_{projectName}OPENAI=sk-...
AGENTCORE_CREDENTIAL_{projectName}ANTHROPIC=sk-ant-...
AGENTCORE_CREDENTIAL_{projectName}GEMINI=...

# OAuth credentials
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_ID=my-client-id
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_SECRET=my-client-secret

# Payment credentials - CoinbaseCDP (3 variables per connector)
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_ID=your-api-key-id
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_SECRET=your-api-key-secret
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_WALLET_SECRET=your-wallet-secret

# Payment credentials - StripePrivy (4 variables per connector)
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_ID=your-app-id
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_SECRET=your-app-secret
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_PRIVATE_KEY=your-private-key
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_ID=your-auth-id

Environment variable names should match the credential names in your configuration. For payment credentials, {CREDENTIAL_NAME} is the connector's credentialName uppercased with hyphens replaced by underscores (e.g., my-cdp-creds becomes MY_CDP_CREDS). See Payments for details.