aws / aws/agentcore-cli

agentcore.json "protocol": "HTTP" is silently dropped — runtime deploys with protocolConfiguration unset, and HTTP cannot be set explicitly

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

Description

### Summary

Declaring `"protocol": "HTTP"` on a runtime in `agentcore.json` is accepted by the schema but **silently never applied**: the CDK construct only forwards `protocolConfiguration` to the L1 `CfnRuntime` when the declared protocol is *not* HTTP. The deployed runtime ends up with `protocolConfiguration` unset, and there is no way to explicitly assert HTTP on the deployed resource.

### Where

`@aws/agentcore-cdk` `0.1.0-alpha.48` (also verified on alpha.45), `dist/cdk/constructs/components/primitives/runtime/AgentCoreRuntime.js`:

```js
const protocolMode = agent.protocol ?? 'HTTP'; // line 246
...
// CfnRuntime.protocolConfiguration is typed as `string | undefined` in the L1,
// so passing 'MCP', 'A2A', or 'AGUI' directly is correct per the CloudFormation spec.
...(protocolMode !== 'HTTP' && { protocolConfiguration: protocolMode }), // line 261
```

So `'MCP'`, `'A2A'`, and `'AGUI'` pass through, but a user-declared `'HTTP'` is indistinguishable from not declaring anything.

### Why it matters

1. **Least surprise**: a value the user explicitly wrote into `agentcore.json` is dropped with no warning. `agentcore status` / the deployed runtime then show no protocol configuration, which reads as "not configured" rather than "configured as HTTP".
2. **It blocks controlled experiments.** We were investigating an idle-session-reaping/billing problem where one hypothesis (from a colleague's test) was that the presence or absence of `protocolConfiguration` on the runtime affected idle-session reaping. There was no declarative way to deploy the "explicitly HTTP" arm — the construct makes that state unreachable. (For the record, our controlled experiment showed reaping works fine with `protocolConfiguration` unset once the agent's `/ping` stops re-stamping `time_of_last_update`; the hypothesis was a confound. But we had to establish the deployed state by inspecting the construct source rather than by declaring it.)

### Expected behaviour (either is fine)

- Pass the declared protocol through unconditionally — if `CreateAgentRuntime`/CloudFormation accepts `HTTP` as an explicit `serverProtocol`, declaring it should set it; **or**
- If HTTP is deliberately omitted because unset means HTTP service-side, document that in the `agentcore.json` schema description for `protocol` (and ideally have the CLI note it at deploy/diff time) so a declared HTTP isn't mistaken for a deploy bug.

### Environment

- `@aws/agentcore` CLI 0.27.0 (which pins the construct; also reproduced reading alpha.48 from npm)
- `@aws/agentcore-cdk` 0.1.0-alpha.45 and 0.1.0-alpha.48
- Runtime deploys verified in eu-west-2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01CiwESpXfsVS2dBrSnMosei

Contributor guide

Open the contributing guide

Research direction

Start at dist/cdk/constructs/components/primitives/runtime/AgentCoreRuntime.js around lines 246-261 and trace how agentcore.json protocol values reach CfnRuntime. Verify the deployed representation for an explicitly declared HTTP protocol, then check the schema description for protocol. Done means HTTP is either forwarded explicitly or the intentional omission is clearly documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, typescript
Domain
cloud
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.