agentcore.json: "unknown keys (remove): agents" after upgrading to v0.4.0 — migration guide for agents→runtimes and type→authorizerType
- 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
Assessment
This issue has not been assessed yet.