fix(cli): vend starter entrypoint for BYO agents (#629)

[aidandaly24]

Refs aws#629

Issues

• feat: add placeholder main.py for BYO agent on project create aws/agentcore-cli#629 — When creating a Bring-Your-Own agent (agentcore create or agentcore add agent --type byo), the CLI makes an empty code directory and only prints a reminder to add the entrypoint yourself. Unlike every template agent type, BYO vends no starter file, so a new user has nothing to run and agentcore dev fails until they hand-author main.py with the right contract. This is an onboarding paper-cut, not a functional defect.

Root cause

handleByoPath() only mkdirSyncs the code dir at AgentPrimitive.tsx:672 and vends no entrypoint, vs handleCreatePath() which renders a full template at :603-605 — confirmed byte-identical at v0.20.2 via git diff/show; entrypoint contract (BedrockAgentCoreApp/@app.entrypoint/app.run) verified in vended main.py:52,77,510,671 and SDK app.py:213,644.

The fix

In handleByoPath() after the mkdirSync at AgentPrimitive.tsx:672, write a starter entrypoint file at join(codeDir, options.entrypoint ?? 'main.py') only when it does not already exist (never overwrite user code). The stub MUST follow the real AgentCore contract, NOT a Lambda handler: from bedrock_agentcore.runtime import BedrockAgentCoreApp; app = BedrockAgentCoreApp(); @app.entrypoint def invoke(payload, context): ...; if name == 'main': app.run(). Two required design decisions: (1) BYO supports --language Python/TypeScript/Other (AgentPrimitive.tsx:260) so gate on language — Python stub for Python, optional TS stub for TypeScript, skip for Other; (2) the filename is user-configurable via --entrypoint (AgentPrimitive.tsx:270, resolved at line 714) so write to the resolved entrypoint name, not a hardcoded main.py. Cleanest implementation is a small BYO placeholder asset under src/assets/ plus a renderer in src/cli/templates/ for consistency with the existing template pipeline; the reminder text at CreateScreen.tsx:98-99 and AddFlow.tsx:145-150 can be softened once a placeholder exists. NOTE: the issue's own suggested stub def handler(event, context): return {'statusCode': 200} is WRONG for this runtime and would fail the 'agentcore dev works out of the box' acceptance criterion.

Files touched: /local/home/aidandal/workplace/issues/agentcore-cli/src/cli/primitives/AgentPrimitive.tsx — handleByoPath() (lines 662-743), add placeholder-file write after mkdirSync at line 672 using the entrypoint resolved at line 714. Optionally add a BYO placeholder asset under src/assets/ + renderer in src/cli/templates/. Reminders at src/cli/tui/screens/create/CreateScreen.tsx:98-99 and src/cli/tui/screens/add/AddFlow.tsx:145-150 may be softened.

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

BEFORE (fix stashed + rebuilt): agentcore add agent --type byo --name myagent --language Python --code-location ./src/myagent --framework Strands --model-provider Bedrock created src/myagent/ EMPTY (0 files) — no entrypoint vended. Confirmed in source: original handleByoPath only did mkdirSync(codeDir).

AFTER (fix restored + rebuilt, run by dist/cli/index.mjs):

• Same command produces src/myagent/main.py (304B) with the AgentCore runtime contract: from bedrock_agentcore.runtime import BedrockAgentCoreApp, app = BedrockAgentCoreApp(), @app.entrypoint def invoke(payload, context), app.run() under if __name__ == "__main__"; contains NO def handler(event, context).
• --entrypoint agent.py honored: stub written to agent.py, no main.py created (resolved name, not hardcoded).
• Pre-existing main.py with hand-written content NOT overwritten (verified byte-for-byte unchanged).
• --language Other: no stub written (0 files), dir still created as before.
• --language TypeScript --entrypoint index.ts: TS stub vended (380B) using BedrockAgentCoreApp from 'bedrock-agentcore/runtime'.
• Contract executed: importing the vended main.py yields a real BedrockAgentCoreApp instance; invoke({'prompt':'hello'}, ctx) returns {'result':'Echo: hello'}; no handler attribute.
• agentcore dev out-of-the-box: with a minimal pyproject.toml declaring bedrock-agentcore (as template agents ship), dev server booted, /ping -> 200, and invocation returned {"result":"Echo: validator ping"} both vi

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.15%	13595 / 36589
🔵	Statements	36.42%	14454 / 39679
🔵	Functions	31.8%	2333 / 7336
🔵	Branches	31.09%	9000 / 28948

Generated in workflow #117 for commit 4027ee4 by the Vitest Coverage Report Action