Skip to content

Commit d41e14b

Browse files
jesseturner21jesseturner21
authored
refactor: rename agents to runtimes (schema, CLI flags, MCP bindings) (#706)
* refactor(schema): rename 'agents' to 'runtimes' in AgentCoreProjectSpec The top-level 'agents' array property in agentcore.json is renamed to 'runtimes' to better reflect the resource type (AgentCoreRuntime). This is a schema-only rename — no changes to CLI commands, flags, or user-facing strings. Scope: JSON schema, Zod schemas, LLM-compacted types, deployed-state, all source references, tests, and documentation. * refactor(cli): rename --agent flags to --runtime across all commands Rename CLI flags from agent terminology to runtime: - --agent <name> → --runtime <name> (with -a → -r short alias) - --agent-runtime-id → --runtime-id - --agent-arn → --runtime-arn - --agents → --runtimes (gateway primitive) Update resolveAgent() to accept { runtime?: string }. Update all action handlers, option types, error messages, and tests. Keep --agent-id and --agent-alias-id unchanged (Bedrock Agent IDs). Keep 'agentcore add agent' / 'agentcore remove agent' commands unchanged. * refactor(schema): rename agentName to runtimeName in MCP bindings and make type optional - Rename `agentName` to `runtimeName` in McpRuntimeBindingSchema and all consuming code (attach.ts, llm-compacted types, JSON schema) - Make `type: "AgentCoreRuntime"` optional on AgentEnvSpec for backward compatibility; stop emitting it in new runtime configs - Update tests to match new schema shape * fix(integ): update add-remove-evaluator test to use --runtime flag The integ test was still using --agent for online-eval commands, which was renamed to --runtime in the CLI flags rename commit. Also removes unused addOnlineEvalArgs variable.
1 parent 8898535 commit d41e14b

File tree

116 files changed

+442
-448
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

116 files changed

+442
-448
lines changed

‎docs/configuration.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
2222
{
2323
"name": "MyProject",
2424
"version": 1,
25-
"agents": [
25+
"runtimes": [
2626
{
2727
"type": "AgentCoreRuntime",
2828
"name": "MyAgent",
@@ -76,7 +76,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
7676
| `name` | Yes | Project name (1-23 chars, alphanumeric, starts with letter) |
7777
| `version` | Yes | Schema version (integer, currently `1`) |
7878
| `tags` | No | Project-level tags applied to all resources |
79-
| `agents` | Yes | Array of agent specifications |
79+
| `runtimes` | Yes | Array of agent specifications |
8080
| `memories` | Yes | Array of memory resources |
8181
| `credentials` | Yes | Array of credential providers (API key or OAuth) |
8282
| `evaluators` | Yes | Array of custom evaluator definitions |
@@ -112,7 +112,7 @@ You can add additional project-level tags by editing the `tags` field in `agentc
112112
"Team": "platform",
113113
"CostCenter": "engineering"
114114
},
115-
"agents": [...],
115+
"runtimes": [...],
116116
"memories": [...]
117117
}
118118
```
@@ -132,7 +132,7 @@ resource-level value takes precedence for that specific resource.
132132
"Environment": "production",
133133
"Team": "platform"
134134
},
135-
"agents": [
135+
"runtimes": [
136136
{
137137
"type": "AgentCoreRuntime",
138138
"name": "MyAgent",
@@ -153,7 +153,7 @@ from project), and `Owner: alice` (resource-specific).
153153

154154
The following resource types support tags:
155155

156-
- **Agents** (`agents` array in `agentcore.json`)
156+
- **Agents** (`runtimes` array in `agentcore.json`)
157157
- **Memories** (`memories` array in `agentcore.json`)
158158
- **Gateways** (`agentCoreGateways` array in `agentcore.json`)
159159
- **Evaluators** (`evaluators` array in `agentcore.json`)

‎e2e-tests/byo-custom-jwt.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ describe.sequential('e2e: BYO agent with CUSTOM_JWT auth', () => {
146146
// ── Patch agent with CUSTOM_JWT auth ──
147147
const specPath = join(projectPath, 'agentcore', 'agentcore.json');
148148
const spec = JSON.parse(await readFile(specPath, 'utf8'));
149-
const agent = spec.agents[0];
149+
const agent = spec.runtimes[0];
150150
agent.authorizerType = 'CUSTOM_JWT';
151151
agent.authorizerConfiguration = {
152152
customJwtAuthorizer: {

‎integ-tests/add-agent-auth.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ describe('integration: add BYO agent with CUSTOM_JWT auth', () => {
5454

5555
// Verify config has authorizer fields
5656
const config = await readProjectConfig(project.projectPath);
57-
const agent = config.agents.find(a => a.name === agentName);
57+
const agent = config.runtimes.find(a => a.name === agentName);
5858
expect(agent, `Agent "${agentName}" should be in config`).toBeTruthy();
5959
expect(agent!.authorizerType).toBe('CUSTOM_JWT');
6060
expect(agent!.authorizerConfiguration).toBeDefined();
@@ -105,7 +105,7 @@ describe('integration: add BYO agent with CUSTOM_JWT auth', () => {
105105
expect(json.success).toBe(true);
106106

107107
const config = await readProjectConfig(project.projectPath);
108-
const agent = config.agents.find(a => a.name === agent2);
108+
const agent = config.runtimes.find(a => a.name === agent2);
109109
expect(agent).toBeTruthy();
110110
expect(agent!.authorizerType).toBe('CUSTOM_JWT');
111111

@@ -152,7 +152,7 @@ describe('integration: add BYO agent with CUSTOM_JWT auth', () => {
152152
expect(result.exitCode, `stdout: ${result.stdout}, stderr: ${result.stderr}`).toBe(0);
153153

154154
const config = await readProjectConfig(project.projectPath);
155-
const agent = config.agents.find(a => a.name === agent3);
155+
const agent = config.runtimes.find(a => a.name === agent3);
156156
expect(agent).toBeTruthy();
157157
// No authorizerType means AWS_IAM default
158158
expect(agent!.authorizerType).toBeUndefined();
@@ -286,7 +286,7 @@ describe('integration: add BYO agent with CUSTOM_JWT auth', () => {
286286
expect(result.exitCode, `stdout: ${result.stdout}, stderr: ${result.stderr}`).toBe(0);
287287

288288
const config = await readProjectConfig(project.projectPath);
289-
const agent = config.agents.find(a => a.name === agent4);
289+
const agent = config.runtimes.find(a => a.name === agent4);
290290
expect(agent).toBeTruthy();
291291

292292
const jwt = agent!.authorizerConfiguration!.customJwtAuthorizer!;

‎integ-tests/add-remove-evaluator.test.ts‎

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -55,20 +55,6 @@ describe('integration: add and remove evaluators and online eval configs', () =>
5555
instructions,
5656
'--json',
5757
];
58-
const addOnlineEvalArgs = [
59-
'add',
60-
'online-eval',
61-
'--name',
62-
configName,
63-
'--agent',
64-
project?.agentName,
65-
'--evaluator',
66-
evalName,
67-
'--sampling-rate',
68-
'50',
69-
'--json',
70-
];
71-
7258
it('adds an evaluator', async () => {
7359
const json = await runSuccess(addEvalArgs, project.projectPath);
7460
expect(json.evaluatorName).toBe(evalName);
@@ -90,7 +76,7 @@ describe('integration: add and remove evaluators and online eval configs', () =>
9076
'online-eval',
9177
'--name',
9278
configName,
93-
'--agent',
79+
'--runtime',
9480
project.agentName,
9581
'--evaluator',
9682
evalName,
@@ -115,7 +101,7 @@ describe('integration: add and remove evaluators and online eval configs', () =>
115101
'online-eval',
116102
'--name',
117103
configName,
118-
'--agent',
104+
'--runtime',
119105
project.agentName,
120106
'--evaluator',
121107
evalName,
@@ -193,7 +179,7 @@ describe('integration: add and remove evaluators and online eval configs', () =>
193179

194180
it('rejects online eval with missing required flags', async () => {
195181
const json = await runFailure(['add', 'online-eval', '--name', 'SomeConfig', '--json'], project.projectPath);
196-
expect(json.error).toContain('--agent');
182+
expect(json.error).toContain('--runtime');
197183
});
198184

199185
it('rejects online eval with invalid sampling rate', async () => {
@@ -203,7 +189,7 @@ describe('integration: add and remove evaluators and online eval configs', () =>
203189
'online-eval',
204190
'--name',
205191
'SomeConfig',
206-
'--agent',
192+
'--runtime',
207193
project.agentName,
208194
'--evaluator',
209195
'SomeEval',

‎integ-tests/create-frameworks.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: create with differen
5757

5858
// Verify config has agent registered
5959
const config = await readProjectConfig(json.projectPath);
60-
const agents = config.agents as Record<string, unknown>[];
60+
const agents = config.runtimes as Record<string, unknown>[];
6161
expect(agents).toBeDefined();
6262
expect(agents.length).toBe(1);
6363
expect(agents[0]!.name).toBe(agentName);
@@ -102,7 +102,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: create with differen
102102

103103
// Verify config has agent registered
104104
const config = await readProjectConfig(json.projectPath);
105-
const agents = config.agents as Record<string, unknown>[];
105+
const agents = config.runtimes as Record<string, unknown>[];
106106
expect(agents.length).toBe(1);
107107
expect(agents[0]!.name).toBe(agentName);
108108
});
@@ -143,7 +143,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: create with differen
143143

144144
// Verify config has agent registered
145145
const config = await readProjectConfig(json.projectPath);
146-
const agents = config.agents as Record<string, unknown>[];
146+
const agents = config.runtimes as Record<string, unknown>[];
147147
expect(agents.length).toBe(1);
148148
expect(agents[0]!.name).toBe(agentName);
149149
});

‎integ-tests/create-protocols.test.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: create with protocol
4242

4343
// Verify config has protocol set to MCP
4444
const config = await readProjectConfig(json.projectPath);
45-
const agents = config.agents as Record<string, unknown>[];
45+
const agents = config.runtimes as Record<string, unknown>[];
4646
expect(agents).toBeDefined();
4747
expect(agents.length).toBe(1);
4848
expect(agents[0]!.name).toBe(agentName);
@@ -87,7 +87,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: create with protocol
8787

8888
// Verify config has protocol set to A2A
8989
const config = await readProjectConfig(json.projectPath);
90-
const agents = config.agents as Record<string, unknown>[];
90+
const agents = config.runtimes as Record<string, unknown>[];
9191
expect(agents.length).toBe(1);
9292
expect(agents[0]!.protocol).toBe('A2A');
9393
});
@@ -118,7 +118,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: create with protocol
118118

119119
// Verify config has explicit protocol: HTTP
120120
const config = await readProjectConfig(json.projectPath);
121-
const agents = config.agents as Record<string, unknown>[];
121+
const agents = config.runtimes as Record<string, unknown>[];
122122
expect(agents.length).toBe(1);
123123
expect(agents[0]!.protocol).toBe('HTTP');
124124
});
@@ -175,7 +175,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: add agent with proto
175175
expect(json.success).toBe(true);
176176

177177
const config = await readProjectConfig(projectPath);
178-
const agents = config.agents as Record<string, unknown>[];
178+
const agents = config.runtimes as Record<string, unknown>[];
179179
const mcpAgent = agents.find(a => a.name === name);
180180
expect(mcpAgent).toBeDefined();
181181
expect(mcpAgent!.protocol).toBe('MCP');
@@ -209,7 +209,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: add agent with proto
209209
expect(json.success).toBe(true);
210210

211211
const config = await readProjectConfig(projectPath);
212-
const agents = config.agents as Record<string, unknown>[];
212+
const agents = config.runtimes as Record<string, unknown>[];
213213
const a2aAgent = agents.find(a => a.name === name);
214214
expect(a2aAgent).toBeDefined();
215215
expect(a2aAgent!.protocol).toBe('A2A');
@@ -241,7 +241,7 @@ describe.skipIf(!prereqs.npm || !prereqs.git)('integration: add agent with proto
241241
expect(json.success).toBe(true);
242242

243243
const config = await readProjectConfig(projectPath);
244-
const agents = config.agents as Record<string, unknown>[];
244+
const agents = config.runtimes as Record<string, unknown>[];
245245
const byoAgent = agents.find(a => a.name === name);
246246
expect(byoAgent).toBeDefined();
247247
expect(byoAgent!.protocol).toBe('MCP');

‎integ-tests/lifecycle-config.test.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ describe('integration: lifecycle configuration', () => {
6464
expect(json.success).toBe(true);
6565

6666
const config = await readProjectConfig(json.projectPath);
67-
const agents = config.agents as Record<string, unknown>[];
67+
const agents = config.runtimes as Record<string, unknown>[];
6868
expect(agents.length).toBe(1);
6969

7070
const agent = agents[0]!;
@@ -101,7 +101,7 @@ describe('integration: lifecycle configuration', () => {
101101
expect(json.success).toBe(true);
102102

103103
const config = await readProjectConfig(json.projectPath);
104-
const agents = config.agents as Record<string, unknown>[];
104+
const agents = config.runtimes as Record<string, unknown>[];
105105
const agent = agents[0]!;
106106
const lifecycle = agent.lifecycleConfiguration as Record<string, unknown>;
107107
expect(lifecycle).toBeDefined();
@@ -134,7 +134,7 @@ describe('integration: lifecycle configuration', () => {
134134
expect(json.success).toBe(true);
135135

136136
const config = await readProjectConfig(json.projectPath);
137-
const agents = config.agents as Record<string, unknown>[];
137+
const agents = config.runtimes as Record<string, unknown>[];
138138
const agent = agents[0]!;
139139
expect(agent.lifecycleConfiguration).toBeUndefined();
140140
});
@@ -173,7 +173,7 @@ describe('integration: lifecycle configuration', () => {
173173
expect(json.success).toBe(true);
174174

175175
const config = await readProjectConfig(projectPath);
176-
const agents = config.agents as Record<string, unknown>[];
176+
const agents = config.runtimes as Record<string, unknown>[];
177177
const agent = agents.find(a => a.name === name);
178178
expect(agent).toBeDefined();
179179
const lifecycle = agent!.lifecycleConfiguration as Record<string, unknown>;
@@ -210,7 +210,7 @@ describe('integration: lifecycle configuration', () => {
210210
expect(json.success).toBe(true);
211211

212212
const config = await readProjectConfig(projectPath);
213-
const agents = config.agents as Record<string, unknown>[];
213+
const agents = config.runtimes as Record<string, unknown>[];
214214
const agent = agents.find(a => a.name === name);
215215
expect(agent).toBeDefined();
216216
const lifecycle = agent!.lifecycleConfiguration as Record<string, unknown>;

‎integ-tests/tui/lifecycle-config.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ describe('Create Flow: Lifecycle Configuration via TUI', () => {
189189
if (projectDirName) {
190190
const projectPath = join(parentDir, projectDirName);
191191
const config = readAgentcoreJson(projectPath);
192-
const agents = config.agents as Record<string, unknown>[];
192+
const agents = config.runtimes as Record<string, unknown>[];
193193
expect(agents.length).toBeGreaterThan(0);
194194

195195
const agent = agents[0]!;
@@ -434,7 +434,7 @@ describe('Add Agent BYO Flow: Lifecycle Configuration via TUI', () => {
434434

435435
// Read the agentcore.json and verify lifecycle config
436436
const config = readAgentcoreJson(projectDir.dir);
437-
const agents = config.agents as Record<string, unknown>[];
437+
const agents = config.runtimes as Record<string, unknown>[];
438438
const agent = agents.find((a: Record<string, unknown>) => a.name === 'ByoLifecycle');
439439
expect(agent, 'Agent should be in agentcore.json').toBeDefined();
440440

‎schemas/agentcore.schema.v1.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
"pattern": "^[\\p{L}\\p{N}\\s_.:/=+\\-@]*$"
3636
}
3737
},
38-
"agents": {
38+
"runtimes": {
3939
"default": [],
4040
"type": "array",
4141
"items": {
@@ -1256,7 +1256,7 @@
12561256
"items": {
12571257
"type": "object",
12581258
"properties": {
1259-
"agentName": {
1259+
"runtimeName": {
12601260
"type": "string",
12611261
"minLength": 1
12621262
},
@@ -1267,7 +1267,7 @@
12671267
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
12681268
}
12691269
},
1270-
"required": ["agentName", "envVarName"],
1270+
"required": ["runtimeName", "envVarName"],
12711271
"additionalProperties": false
12721272
}
12731273
}

‎src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -377,7 +377,7 @@ test('AgentCoreStack synthesizes with empty spec', () => {
377377
name: 'testproject',
378378
version: 1,
379379
managedBy: 'CDK' as const,
380-
agents: [],
380+
runtimes: [],
381381
memories: [],
382382
credentials: [],
383383
evaluators: [],

0 commit comments

Comments
 (0)