fix(import): translate Bedrock Agents into owned runtime code instead of proxying them

[aidandaly24]

Context

PR #2146 added project create --type import and project add runtime --type import. As merged, --type import scaffolded a proxy: a generated main.py that called bedrock-agent-runtime:InvokeAgent on the source alias for every request. This PR originally hardened that proxy against eight post-merge defects.

Review feedback pointed out that the proxy is the wrong feature. The pre-refactor CLI on main implements import as a one-time translation: it reads the agent definition, action groups, knowledge bases, guardrails, model settings, and collaborators, then generates runnable Strands or LangGraph Python that the customer owns and edits (src/cli/aws/bedrock-import.ts, src/cli/operations/agent/import/*, documented in docs/frameworks.md). The proxy kept the source alias on the request path permanently, generated no prompts or tools, and broke if the alias moved or was deleted.

This PR was reworked to restore that contract. It does not change --type create.

What changed

--type import now resolves the selected alias to its immutable agent version and translates that version into customer-owned Python. The generated application invokes models and translated tools directly and keeps working after the source alias is deleted.

• The loader uses GetAgentVersion, never GetAgent, so mutable draft edits cannot leak into the snapshot. Action groups, knowledge bases, and collaborators are read at that same version, paginated, with cycle protection.
• --framework strands|langgraph (default strands) and the existing --memory options both apply to import, shared identically by project create and project add runtime.
• Generated files go through FsTreeNode/ProjectManager, so writes, rollback, dependency installation, and spec ownership stay in the project layer.
• Behavior that cannot be translated cleanly is recorded in IMPORT_NOTES.md rather than silently claimed: OpenAPI and Lambda action groups, user-input actions, Strands guardrails, custom prompt templates, collaborator session scope, and the exact bedrock:Retrieve permissions the execution role needs. OpenAPI actions, Lambda executors, user-input actions, relayed collaborator history, and generated IAM policy documents are deliberately not implemented.
• Removed: the proxy template, the alias invocation policy, alias-readiness warnings, Bedrock session-ID normalization, and the two-method BedrockAgentControlClient wrapper, replaced by a single CoreBedrockAgentImporter.import(request) -> plan seam.

Five of the eight defects the original PR fixed were properties of the proxy and are eliminated by removing it: alias-readiness checks, the caller-owned-role policy, and Bedrock session-ID normalization no longer have anything to apply to. Three are retained: service-response validation, protocol validation before any AWS call, and payload-shape validation. The region list is retained and completed, since the earlier fix still omitted ap-northeast-2 and us-east-2.

Bugs fixed while porting

1. Bedrock's own defaults were copied into generated code

GetAgentVersion echoes the service's internal orchestration template and inference settings, for example temperature: 1 and a </answer> stop sequence, even when the customer never overrode them. It also populates additionalModelRequestFields on the ORCHESTRATION prompt of a completely default agent. Copying any of that makes service internals the generated agent's behavior, and the last case produced an IMPORT_NOTES.md entry telling the customer to migrate prompt customization that did not exist. The loader now reads prompt and inference settings only when promptCreationMode or parserMode is OVERRIDDEN; otherwise the agent instruction is the system prompt.

2. Collaborator modules registered a second Runtime entrypoint

Each generated collaborator module created its own BedrockAgentCoreApp() and @app.entrypoint, and the root module imports it, so a second entrypoint registered at import time. Only the root module owns the entrypoint now.

3. Collaborator follow-up was never reported

Notes were collected for the root agent only, so a collaborator's unimplemented action groups and knowledge-base permissions never reached IMPORT_NOTES.md. Notes now cover the whole agent tree and name the collaborator. A collaborator-only code interpreter also produced an import with no matching dependency; the pyproject.toml dependency is now computed across the tree.

4. The default test alias failed with an unmapped service error

TSTALIASID routes to the mutable DRAFT version, which has no GetAgentVersion representation. Import now rejects it before any further call and explains how to create a version and an alias. The README example used TSTALIASID and would itself have failed; both it and the --agent-alias-id help text now state the constraint.

5. Cross-region knowledge bases were retrieved from the wrong region

Retrieval used the agent's region. It now uses the region in the knowledge base's own ARN.

6. Importing a supervisor agent dropped every collaborator

A supervisor agent imported as a bare agent: no collaborator modules, no tools, and one misleading collaborator-cycle note per collaborator naming the supervisor's own agent id.

On a ListAgentCollaborators summary, agentId and agentVersion describe the supervisor that owns the collaboration, not the collaborator; only agentDescriptor.aliasArn identifies the collaborator. Reading agentId resolved every collaborator to its own parent, which the visited set had already seen, so each was discarded as a false cycle. Pre-refactor main read only the alias ARN — the fallback was introduced during the port.

Collaborators are now resolved from the alias ARN, and their alias is resolved to an immutable version the same way the requested agent's is, through one shared helper that also rejects DRAFT.

Both existing collaborator tests passed against the broken code because their fixtures placed the collaborator's id in agentId, which the service never does. Both now use the real shape, and a new test asserts the verbatim two-collaborator response observed live.

7. Generated dependencies were unbounded

Dependencies used >= with no upper bound, and one was unpinned entirely, so a major release could break an imported project. They now use ~= like the scaffolded templates, bounded at the minor rather than the patch: copying the templates' patch-level pin exactly would ship a broken project, because langgraph ~= 1.0.2 resolves to 1.0.10, whose langgraph-prebuilt imports a symbol its own langgraph.runtime does not export.

Validation

Automated

• bun test src
  • 2,763 passed, 0 failed across 201 files
• bun run typecheck
• bun run lint:check
• bun run format:check
• bun run secrets:check
• bun run build

Generated Python

• Compiled every combination of framework (Strands, LangGraph), memory (none, longAndShortTerm), and shape (with collaborators, tools, and knowledge bases; and bare).
• Resolved both generated projects with uv sync and imported them, including the memory module.
• Asserted the generated code contains no InvokeAgent call path and exactly one BedrockAgentCoreApp/@app.entrypoint per project.

Live AWS lifecycle

Two full deployments in account 603141041947, us-east-1, against this branch's bundled CLI: one Strands import with --memory none, and one LangGraph import with --memory longAndShortTerm. Each used a source Bedrock Agent whose instruction demanded a fixed token prefix, so a correct reply proves the instruction survived translation.

• --agent-alias-id TSTALIASID was rejected with the new guidance before any further service call, and --region eu-north-1 was rejected locally.
• Imported the alias, resolved dependencies, synthesized, and deployed the runtime. The generated project contained no reference to the source alias ID and no InvokeAgent call path, and the runtime spec carried no additionalPolicies.
• Invoked successfully, then deleted the source alias, confirmed GetAgentAlias returned ResourceNotFoundException, and invoked again successfully. Every response began with the token the source agent's instruction required, so the instruction survived translation.
• [] and {} payloads returned a controlled validation error without reaching the model.
• Two sessions were isolated: the first recalled a fact it was given, the second did not know it.

The LangGraph run additionally exercised generated memory, which no earlier validation reached:

• The memory resource was created with all four strategies and the runtime received the MEMORY_*_ID environment variable the generated code reads.
• Events written by the generated agent were confirmed present in AgentCore Memory, and were attributed to the caller's actor when userId was supplied in the payload.
• Same-session recall worked through the LangGraph thread_id; a second session did not see the first session's facts.

A third deployment covered multi-agent collaboration, importing a supervisor with a billing collaborator (relay TO_COLLABORATOR) and a weather collaborator:

• Both collaborator modules were generated and wired as tools, each carrying its own instruction, and exactly one BedrockAgentCoreApp/@app.entrypoint existed across the project, in main.py.
• The relay follow-up note appeared only for billing, matching the source configuration.
• After deployment the supervisor answered with both its own and the collaborator's instruction tokens in one reply (SUPERVISOR: ... BILLING: ...), so the generated collaborator module executed rather than being inlined or ignored.

After all three runs the stack, runtime, memory, source agents, aliases, and IAM roles were confirmed deleted.

Not exercised against AWS, and unit-tested only: knowledge-base retrieval, action-group stubs, code interpreter, and guardrails.

Out of scope

• project create --type create behaviour is unchanged.
• OpenAPI/Lambda action implementations, user-input actions, and relayed collaborator history remain manual follow-up, surfaced in IMPORT_NOTES.md.
• The scaffolded templates pin bedrock-agentcore ~= 1.9.1, which resolves to exactly 1.9.1. That affects five templates and is left alone here.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.30435% with 77 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.14%. Comparing base (6357f2e) to head (6926b87).
⚠️ Report is 2 commits behind head on refactor.

Files with missing lines	Patch %	Lines
.../project/bedrockAgentImport/langGraphTranslator.ts	67.66%	65 Missing ⚠️
src/handlers/project/create/index.ts	77.14%	8 Missing ⚠️
src/handlers/project/add/runtime/index.ts	94.28%	2 Missing ⚠️
src/core/project/bedrockAgentImport/loader.ts	99.73%	1 Missing ⚠️
src/core/project/templates/runtime.ts	95.23%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           refactor    #2153    +/-   ##
==========================================
  Coverage     97.14%   97.14%            
==========================================
  Files           519      526     +7     
  Lines         35492    36458   +966     
==========================================
+ Hits          34478    35418   +940     
- Misses         1014     1040    +26     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Reviewed the eight fixes against bedrockAgent.ts, importBedrockAgent.ts, templates/runtime.ts, and the Python proxy template. The changes are well-scoped, all failure modes are covered by tests at real I/O boundaries (control-plane client injection, in-memory describeBedrockAgent fakes), and the live-lifecycle validation in the description confirms the caller-owned-role and long-session-id paths end-to-end.

A few things I looked at and am comfortable with:

• Session-id normalization (main.py): 64-char SHA-256 hex matches the ^[0-9A-Za-z._:-]{2,100}$ pattern, non-string/empty inputs correctly fall through to a fresh UUID, and empty context.session_id short-circuits to payload.get("sessionId") as intended.
• Response validation (bedrockAgent.ts): agent.agentId / agent.agentName are now checked before getAgentAlias, and the alias response is cross-checked against the requested IDs, which is what the description promised.
• additionalPolicies omission with executionRoleArn (templates/runtime.ts): the generated bedrock-agent-policy.json file is preserved for the user to attach manually, and the README template branches on usesExistingExecutionRole to match — I traced both branches through importBedrockAgentResolver and the rendered README.
• Protocol pre-check in add/runtime/index.ts correctly runs before resolveImportBedrockAgentInput, so --protocol MCP no longer triggers a Bedrock describe call (verified by the new rejects a non-HTTP protocol before describing the agent test).

One minor observation, not blocking: bedrockAgent.ts switched from await import("@aws-sdk/client-bedrock-agent") to a top-level static import. This is consistent with src/core/invokeRuntime.ts (which also statically imports an AWS SDK command class on a hot handler path), so it's aligned with existing convention — just noting the deviation from the previous lazy-load pattern in case CLI cold-start latency is being tracked.

Nice work.

[AlexanderRichey]

Hah it looks like the AI didn't actually import this feature properly. It just proxies to Bedrock Agents. 😆

We'll have to implement this properly. I think we already have the code. We just need to port it over.

[AlexanderRichey]

What's the upshot of this interface?

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)