Setting the file. One moment.
Subchapter 23.21
references/migrate-bedrock-agents-to-agentcore-harness.mdMarkdown11 KBView on GitHub
Migrate a Bedrock Agent into an AgentCore Harness (the managed agent loop) using the AgentCore CLI. The skill drives the CLI to scaffold and deploy; it never hand-rolls boto3 infrastructure the CLI owns. Remeber that this skill can be used for performing the migration AND helping the user answer any migration related questions even if they don’t want to perform the migration.
Assets
Kb Shim PyReference files, scripts and templates are available in references (opens in a new tab)
Inline agents. This guidance also migrates a Bedrock inline agent (one invoked via InvokeInlineAgent with its configuration supplied per-request rather than persisted as a stored agent). An inline agent has no agentId, so it takes a modified entry path: its InvokeInlineAgent request payload is the source manifest. Concretely — skip Phase 0’s agent-region confirm and all of Phase 1 (identity resolution) and Phase 2’s fetch (fetch_bedrock_agent.py needs an --agent-id an inline agent doesn’t have); instead, take the user-supplied InvokeInlineAgent payload, extract its components (foundationModel, instruction, actionGroups, knowledgeBases, guardrailConfiguration, prompt overrides), write them into ./out/source-agent.json in the manifest shape (bedrock-agents-to-agentcore-harness/discovery.md (opens in a new tab)), then enter at Phase 3. Every phase from Phase 3 on — eligibility gates, component mapping, deploy — applies unchanged, since they operate on the manifest, not on how it was obtained.
Two ideas run through every phase:
This skill makes AWS API calls throughout (STS, Bedrock Agent reads, deploys). The AWS MCP server is recommended for streamlined access, but is not required — every step also works with the AWS CLI and boto3 as described here.
The triggering request is the input. Extract whatever the user gave — agent id/name/ARN, region, profile/account — and confirm it in the phases below rather than re-asking. Identity resolution (Phase 1) runs after preflight, since listing agents to disambiguate a name needs a confirmed account + region first.
Fail fast. If the request already names a hard-stop disqualifier (multi-agent, custom orchestration, multimodal), say so and stop before preflight — always with that condition’s specific alternative from bedrock-agents-to-agentcore-harness/eligibility.md (opens in a new tab), never a bare “not supported.” Phase 3 still runs the full gate for everything that clears this.
Finish each phase and summarize before the next.
Establish the migration runs against the account, region, and CLI the user intends — before touching the source agent.
aws sts get-caller-identity. Echo the account id, caller ARN, and resolved region back to the user and ask them to confirm or correct before proceeding. Never assume the default profile is the right one.Completion criterion: the user has confirmed (account, region) and the CLI passed its checks.
Inline agents skip this phase (they have no agentId; see “Inline agents” above — take the payload and enter at Phase 3).
Resolve a concrete (agentId, agentVersion, aliasId) from whatever the user gave (id, name, ARN, or nothing). If the user gave a name fragment, gave nothing, or asks to see what’s available, list the agents in the confirmed region (bedrock-agent:ListAgents) and present them for the user to pick from. Default to the production alias’s numbered version, not DRAFT — unless the user has only DRAFT or asks for it explicitly. See bedrock-agents-to-agentcore-harness/discovery.md (opens in a new tab) for resolution rules and the DRAFT-only case.
Completion criterion: the user has confirmed the exact (account, region, agentId, agentVersion, aliasId) tuple.
Snapshot the agent into one manifest (./out/source-agent.json) — via the bundled scripts/fetch_bedrock_agent.py (needs python3 + boto3), or the aws bedrock-agent fallback when boto3 is absent. Both paths and the manifest shape are in bedrock-agents-to-agentcore-harness/discovery.md (opens in a new tab). For an inline agent the fetch script does not apply (no agentId) — build the manifest from the InvokeInlineAgent payload instead, per “Inline agents” above and discovery.md’s inline note.
Read the manifest and present a concise, human-readable inventory — a scannable list or small table (model; action groups by name + type; KBs + type; guardrail; memory; collaboration), not a prose paragraph.
Also capture the source’s security posture so the migration can preserve it (see bedrock-agents-to-agentcore-harness/deploy.md (opens in a new tab)): its inbound invocation posture (which principals hold bedrock-agent-runtime:InvokeAgent, plus any resource-based policy on the agent) and its idleSessionTTLInSeconds. These set the bar Phase 6 must match, not loosen.
Completion criterion: manifest written and inventory presented.
Check the manifest against the eligibility rubric in bedrock-agents-to-agentcore-harness/eligibility.md (opens in a new tab). Any hard-stop condition (multimodal input, multi-agent collaboration, unreachable KB, custom orchestration) ends the migration here.
If a gate fails: stop, tell the user exactly which condition failed and why, and suggest manual alternatives.
Completion criterion: every hard-stop condition checked and explicitly cleared, or the migration stopped with a reported reason.
The agent is eligible, but not every component migrates with full fidelity. Before planning, show the user a per-component ledger classifying each discovered component three ways:
Use the mapping in bedrock-agents-to-agentcore-harness/mapping.md (opens in a new tab) to classify. Present the ledger and pause for explicit acknowledgement — the user must accept the degraded and cannot items before planning. Nothing irreversible has happened yet; this is informed consent on fidelity loss.
Completion criterion: user has seen the full ledger and acknowledged the degraded/cannot items.
Map each acknowledged component to its harness target using bedrock-agents-to-agentcore-harness/mapping.md (opens in a new tab). Produce a written migration plan and pause for approval (gate). Surface costs and that the source agent is never modified.
Completion criterion: user approved the written plan.
Drive the CLI per the approved plan, following bedrock-agents-to-agentcore-harness/deploy.md (opens in a new tab) end to end: scaffold with plain agentcore create, deploy the shim Lambdas, add gateway/gateway-target/harness, then the two-phase deploy. On scaffolding specifically: use agentcore create with no flags. Do not use agentcore create --import (or agentcore import) — that flag does exist, but it imports the Bedrock Agent into a code project, not a Harness, so it is the wrong route for this migration. There is no agentcore init command. Set the deploy region before the first deploy (deploy.md’s region trap). Generate shim code and tool schemas by adapting the .tmpl templates in assets/ per bedrock-agents-to-agentcore-harness/mapping.md (opens in a new tab). Configure the harness/gateway inbound auth to match the source’s invocation posture discovered in Phase 2 (deploy.md “Inbound auth”) — do not accept the CLI default if it is broader. If deploy fails, surface the error — fail loudly, never silently work around it. In particular, if a shim invocation fails with AccessDenied, do not run aws lambda add-permission on the source — that mutates source-side infra; stop and hand the builder the command (deploy.md “Source-side prerequisites”).
Completion criterion: agentcore deploy reports success. Verification is deploy-success-only; deeper parity is out of scope.
assume-role) for both discovery and deploy — never long-lived IAM user access keys.AccessDenied, stop and ask the builder to grant the shim role lambda:InvokeFunction on the source (deploy.md “Source-side prerequisites”) — never run add-permission on the source itself.