aws / aws/agentcore-cli

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

Open
#719 1 comment 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
283
Forks
95
Avg merge
1d 2h
Merged PRs (30d)
183

Description

## 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`
```diff
- "agents": [
+ "runtimes": [
```

### 2. Remove `type` field from each runtime entry
```diff
{
- "type": "AgentCoreRuntime",
"name": "MyAgent",
"build": "CodeZip",
...
}
```

### 3. Rename `type` → `authorizerType` in each credential entry
```diff
{
- "type": "OAuthCredentialProvider",
+ "authorizerType": "OAuthCredentialProvider",
"name": "my-oauth-cred",
...
}
```
```diff
{
- "type": "ApiKeyCredentialProvider",
+ "authorizerType": "ApiKeyCredentialProvider",
"name": "my-api-key",
...
}
```

### Full before/after example

**Before** (old schema):
```json
{
"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):
```json
{
"$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`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.