refactor: rename agents to runtimes (schema, CLI flags, MCP bindings) by jesseturner21 · Pull Request #706 · aws/agentcore-cli

jesseturner21 · 2026-03-27T18:49:48Z

Description

Renames agent terminology to runtime across schema, CLI flags, and MCP bindings to better reflect the resource type (AgentCoreRuntime). This is a breaking change to the agentcore.json schema.

Commit 1: Schema rename `agents` → `runtimes`

JSON schema: agentcore.schema.v1.json property "agents" → "runtimes"
Zod schemas: agentcore-project.ts, deployed-state.ts
LLM-compacted types: agentcore.ts, mcp.ts
Source files: All .agents property accesses on AgentCoreProjectSpec and DeployedResourceState → .runtimes
Tests: All test fixtures and assertions updated
Docs: configuration.md JSON examples updated

Commit 2: CLI flags `--agent` → `--runtime`

--agent <name> → --runtime <name> (with -a → -r short alias)
--agent-runtime-id → --runtime-id
--agent-arn → --runtime-arn
--agents → --runtimes (gateway primitive)
resolveAgent() updated to accept { runtime?: string }
All action handlers, option types, error messages, and tests updated
Unchanged: --agent-id, --agent-alias-id (Bedrock Agent IDs), agentcore add agent / agentcore remove agent command names

Commit 3: MCP bindings `agentName` → `runtimeName`

McpRuntimeBindingSchema.agentName → runtimeName
attach.ts binding logic updated
JSON schema, LLM-compacted types, and tests updated

NOT changed (intentionally):

ParsedStarterToolkitConfig.agents — external YAML parser type
CLI command names (add agent, remove agent)
--agent-id and --agent-alias-id (Bedrock Agent identifiers)
Directory paths in codeLocation values

Related Issue

Closes #

Documentation PR

Type of Change

Testing

I ran npm run test:unit and npm run test:integ
I ran npm run typecheck
I ran npm run lint
If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Results:

TypeScript: 0 errors
Unit tests pass (5 pre-existing failures from main: 2 PTY env issues, 3 from PR refactor(schema): remove type fields from resource schemas and rename credential discriminator #709 credential discriminator rename)
End-to-end tested: create → validate → deploy → status → invoke with --runtime flag

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

Companion PR: https://github.com/aws/agentcore-l3-cdk-constructs/pull/124

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

github-actions · 2026-03-27T18:50:41Z

Package Tarball

aws-agentcore-0.3.0-preview.9.0.tgz

How to install

npm install https://github.com/aws/agentcore-cli/releases/download/pr-706-tarball/aws-agentcore-0.3.0-preview.9.0.tgz

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.

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.

… 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

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.

github-actions · 2026-03-27T22:41:32Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	46%	6553 / 14243
🔵	Statements	45.57%	6963 / 15277
🔵	Functions	44.71%	1176 / 2630
🔵	Branches	46.09%	4331 / 9395

Generated in workflow #1487 for commit 20d0c04 by the Vitest Coverage Report Action

Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in aws#706.

) * docs: fix 30 documentation inaccuracies found by source code audit - configuration.md: fix networkMode PRIVATE→VPC, remove stale mcp.json section, add 7 missing AgentEnvSpec fields, add Node.js runtimes, fix gateway name max 63→100, list all 6 targetType values, fix memory strategies wording, fix deployed-state.json path, add missing project fields, fix CUSTOM_JWT field requirements, add customClaims field - README.md: add CrewAI framework, update all 4 default model IDs, add missing command sections - frameworks.md: add CrewAI with model providers, add protocol compatibility matrix (HTTP/MCP/A2A) - commands.md: fix agent name max 64→48 chars, add fetch access section, add policy-engine/policy to status --type, remove ghost --tool-filter-description flag, fix model ID date - gateway.md: add enableSemanticSearch/exceptionLevel config options, fix mcp.json→agentcore.json, remove api-key from MCP Server auth - transaction_search.md: fix traces command syntax - container-builds.md: remove nonexistent --progress flag - evals.md: fix model date 20250929→20250514 - local-development.md: fix mcp.json→agentcore.json - AGENTS.md: remove AutoGen, remove stale mcp.json reference - src/assets/README.md: add CrewAI to template list - src/assets/agents/AGENTS.md: remove AutoGen Constraint: All fixes verified against Zod schemas and CLI runtime Constraint: CLI --help text bugs left for separate agent Confidence: high Scope-risk: narrow * style: run prettier on documentation files * test: update asset snapshots for edited README.md and AGENTS.md * ci: trigger build workflow * docs: update docs for upstream schema refactor and naming unification - Remove `type` fields from agent, memory, evaluator, online-eval-config examples and field tables (removed in #709) - Remove `modelProvider` from agent spec (removed in #709) - Rename credential `type` to `authorizerType` (renamed in #709) - Rename `add identity` to `add credential` everywhere (#705) - Replace `--force` with `-y/--yes` on remove commands (#705) - Replace `--plan` with `--dry-run` on deploy command (#705) - Update snapshot for src/assets/README.md change * docs: fix stale agents reference in gateway example Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in #706. * docs: rename --agent flags to --runtime and remove stale type fields Update all documentation to reflect upstream renames: - --agent → --runtime, -a → -r across all commands - --agent-arn → --runtime-arn, --agent-runtime-id → --runtime-id - Remove stale "type" fields from JSON examples in evals.md, memory.md, and container-builds.md Constraint: --agent-id, --agent-alias-id, --agent-client-id, --agent-client-secret are unchanged (different semantics) Constraint: --type agent filter value in status/fetch stays as-is Confidence: high Scope-risk: narrow * docs: add missing flags and fix --lines → --limit - Add -H, --header flag to dev and invoke commands - Add --bearer-token flag to invoke command - Fix --lines → --limit in evals.md logs evals section Confidence: high Scope-risk: narrow * docs: fix stale gateway flags and add missing CLI flags - Rename --agent-client-id → --client-id, --agent-client-secret → --client-secret in gateway docs (naming unification #705) - Add missing flags to add agent: --authorizer-type, --discovery-url, --allowed-audience, --allowed-clients, --allowed-scopes, --custom-claims, --client-id, --client-secret, --idle-timeout, --max-lifetime - Add missing flags to create: --idle-timeout, --max-lifetime - Add missing flags to add gateway: --runtimes, --custom-claims, --policy-engine, --policy-engine-mode - Fix --exception-level values: NONE/ALL (was undocumented) Confidence: high Scope-risk: narrow * docs: fix --exception-level valid values to NONE/DEBUG The CLI help text says ALL but the schema (GatewayExceptionLevelSchema) defines the valid values as NONE and DEBUG. Aligns commands.md with gateway.md and the Zod schema. * docs: fix stale fields and add flags from upstream v0.5–v0.7 - Remove stale "type": "AgentCoreMemory" from memory streaming example - Add memory streaming flags: --delivery-type, --data-stream-arn, --stream-content-level, --stream-delivery-resources - Add --exec to dev command flag table (Container agents) - Add --skip-install to create command flag table - Add --identity-name to fetch access flag table

jesseturner21 requested a review from a team March 27, 2026 18:49

github-actions Bot added the size/l PR size: L label Mar 27, 2026

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 18:49 — with GitHub Actions Failure

github-actions Bot removed the size/l PR size: L label Mar 27, 2026

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 21:50 — with GitHub Actions Failure

github-actions Bot added the size/l PR size: L label Mar 27, 2026

jesseturner21 force-pushed the rename-agents-to-runtimes branch from a845ed9 to 624d538 Compare March 27, 2026 22:18

github-actions Bot added size/l PR size: L and removed size/l PR size: L labels Mar 27, 2026

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 22:18 — with GitHub Actions Failure

jesseturner21 added 3 commits March 27, 2026 18:18

jesseturner21 force-pushed the rename-agents-to-runtimes branch from 624d538 to ffd1bf0 Compare March 27, 2026 22:19

github-actions Bot added size/l PR size: L and removed size/l PR size: L labels Mar 27, 2026

jesseturner21 changed the title ~~refactor(schema): rename 'agents' to 'runtimes'~~ refactor: rename agents to runtimes (schema, CLI flags, MCP bindings) Mar 27, 2026

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 22:25 — with GitHub Actions Failure

fix(integ): update add-remove-evaluator test to use --runtime flag

9a165c6

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.

github-actions Bot added size/l PR size: L and removed size/l PR size: L labels Mar 27, 2026

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 22:33 — with GitHub Actions Failure

Merge branch 'main' into rename-agents-to-runtimes

20d0c04

github-actions Bot removed the size/l PR size: L label Mar 27, 2026

github-actions Bot added the size/l PR size: L label Mar 27, 2026

jesseturner21 commented Mar 27, 2026

View reviewed changes

Comment thread integ-tests/add-remove-evaluator.test.ts

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 22:41 — with GitHub Actions Failure

jesseturner21 commented Mar 27, 2026

View reviewed changes

Comment thread src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts

Hweinstock approved these changes Mar 27, 2026

View reviewed changes

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 22:56 — with GitHub Actions Failure

jesseturner21 merged commit d41e14b into main Mar 27, 2026
23 of 27 checks passed

jesseturner21 deleted the rename-agents-to-runtimes branch March 27, 2026 22:57

aidandaly24 added a commit to aidandaly24/agentcore-cli that referenced this pull request Mar 27, 2026

docs: fix stale agents reference in gateway example

9ebf021

Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in aws#706.

aidandaly24 mentioned this pull request Mar 28, 2026

docs: fix 30 documentation inaccuracies found by source code audit #697

Merged

15 tasks

aidandaly24 added a commit to aidandaly24/agentcore-cli that referenced this pull request Mar 28, 2026

docs: fix stale agents reference in gateway example

bc4a594

Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in aws#706.

aidandaly24 added a commit to aidandaly24/agentcore-cli that referenced this pull request Mar 28, 2026

docs: fix stale agents reference in gateway example

becd4fb

Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in aws#706.

aidandaly24 added a commit to aidandaly24/agentcore-cli that referenced this pull request Mar 28, 2026

docs: fix stale agents reference in gateway example

c51927f

Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in aws#706.

aidandaly24 added a commit to aidandaly24/agentcore-cli that referenced this pull request Apr 8, 2026

docs: fix stale agents reference in gateway example

f8f8286

Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in aws#706.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: rename agents to runtimes (schema, CLI flags, MCP bindings)#706

refactor: rename agents to runtimes (schema, CLI flags, MCP bindings)#706
jesseturner21 merged 5 commits intomainfrom
rename-agents-to-runtimes

jesseturner21 commented Mar 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 27, 2026

Uh oh!

Uh oh!

github-actions Bot commented Mar 27, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jesseturner21 commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Commit 1: Schema rename agents → runtimes

Commit 2: CLI flags --agent → --runtime

Commit 3: MCP bindings agentName → runtimeName

NOT changed (intentionally):

Related Issue

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

github-actions Bot commented Mar 27, 2026

Package Tarball

How to install

Uh oh!

Uh oh!

github-actions Bot commented Mar 27, 2026

Coverage Report

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jesseturner21 commented Mar 27, 2026 •

edited

Loading

Commit 1: Schema rename `agents` → `runtimes`

Commit 2: CLI flags `--agent` → `--runtime`

Commit 3: MCP bindings `agentName` → `runtimeName`