agentcore.json: "unknown keys (remove): agents" after upgrading to v0.4.0 — migration guide for agents→runtimes and type→authorizerType

[aidandaly24]

Description

Upgrading to agentcore v0.4.0 introduces breaking schema changes to agentcore.json that prevent existing projects from validating or deploying. The CLI rejects old projects with:

[error]   Validate project
          → /path/to/project/agentcore/agentcore.json:
  - root: unknown keys (remove): "agents"

The new CLI version renamed agents to runtimes and changed the credential discriminator field from type to authorizerType, but provides no migration path, migration command, or documentation for users upgrading existing projects.

Steps to Reproduce

1. Have an existing AgentCore project created with a pre-v0.4.0 CLI version
2. Install agentcore v0.4.0 globally
3. cd into the existing project
4. Run agentcore validate or agentcore deploy
5. Observe the validation error about unknown key "agents"

Behavior

The CLI rejects the config with a cryptic Zod validation error (unknown keys (remove): "agents") and refuses to deploy. Users have no guidance on how to update their config.

If credentials also use the old type field, a second error appears after fixing agents:

- credentials[0]: unknown keys (remove): "type"

Manual Migration Guide

There are three manual changes required to migrate an old project:

1. Rename agents → runtimes

- "agents": [
+ "runtimes": [

2. Remove type field from each runtime entry

  {
-   "type": "AgentCoreRuntime",
    "name": "MyAgent",
    "build": "CodeZip",
    ...
  }

3. Rename type → authorizerType in each credential entry

  {
-   "type": "OAuthCredentialProvider",
+   "authorizerType": "OAuthCredentialProvider",
    "name": "my-oauth-cred",
    ...
  }

  {
-   "type": "ApiKeyCredentialProvider",
+   "authorizerType": "ApiKeyCredentialProvider",
    "name": "my-api-key",
    ...
  }

Full before/after example

Before (old schema):

{
  "name": "MyProject",
  "version": 1,
  "agents": [
    {
      "type": "AgentCoreRuntime",
      "name": "MyAgent",
      "build": "CodeZip",
      "entrypoint": "main.py",
      "codeLocation": "app/MyAgent/",
      "runtimeVersion": "PYTHON_3_12",
      "networkMode": "PUBLIC",
      "modelProvider": "Bedrock",
      "protocol": "HTTP"
    }
  ],
  "credentials": [
    {
      "type": "OAuthCredentialProvider",
      "name": "my-oauth",
      "discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
      "vendor": "CustomOauth2"
    }
  ],
  "memories": [],
  "evaluators": [],
  "onlineEvalConfigs": [],
  "policyEngines": []
}

After (new schema):

{
  "$schema": "https://schema.agentcore.aws.dev/v1/agentcore.json",
  "name": "MyProject",
  "version": 1,
  "managedBy": "CDK",
  "runtimes": [
    {
      "name": "MyAgent",
      "build": "CodeZip",
      "entrypoint": "main.py",
      "codeLocation": "app/MyAgent/",
      "runtimeVersion": "PYTHON_3_12",
      "networkMode": "PUBLIC",
      "modelProvider": "Bedrock",
      "protocol": "HTTP"
    }
  ],
  "credentials": [
    {
      "authorizerType": "OAuthCredentialProvider",
      "name": "my-oauth",
      "discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
      "vendor": "CustomOauth2"
    }
  ],
  "memories": [],
  "evaluators": [],
  "onlineEvalConfigs": [],
  "policyEngines": []
}

Note: The $schema and managedBy fields are optional — the new CLI adds them to newly created projects, but their absence doesn't cause validation failures. The three required changes are: agents → runtimes, remove type from runtimes, and type → authorizerType in credentials.

Suggested Fix

Consider one or more of:

1. Add an agentcore migrate command that rewrites old configs automatically
2. Add a Zod .transform() that maps old keys to new ones at parse time
3. Detect the old agents key and emit a specific error: "The agents field was renamed to runtimes in v0.4.0. Please update your agentcore.json."

CLI Version

0.4.0

[govindhi]

Along with the 3 changes suggested above, we need the following changes as well to get 0.4.0 working after upgraded from preview-9.0

1. Upgrade agentcore cdk - npm install @aws/agentcore-cdk@latest
2. agentcore/cdk/test/cdk.test.ts - Rename agents to runtimes and add managedBy: 'CDK' in the AgentCoreSDK.