# How to Migrate from Amazon Bedrock Agent to AWS AgentCore: A Complete Guide

> Easily migrate from Amazon Bedrock Agent to AWS AgentCore using the agentcore CLI. This guide covers updating SDK calls and prompt adjustments for a seamless transition.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: migration-guide
- Published: 2026-07-01

---

**Migrating from Amazon Bedrock Agent to AWS AgentCore involves using the `agentcore create --type import` command to scaffold a new codebase, updating client SDK calls from `bedrockagent-runtime` to `AgentCoreClient`, and adjusting prompts to handle JSON instead of XML tool results.**

AWS AgentCore (formerly Bedrock AgentCore) provides a **code-first runtime** for building generative-AI agents with richer tooling and custom orchestration compared to the console-driven Amazon Bedrock Agent. The **Agent Toolkit for AWS** repository includes a guided migration workflow that converts existing Bedrock Agent configurations into AgentCore projects, enabling version control, advanced observability, and custom orchestration with Strands or LangGraph.

## Prerequisites

Before starting the migration, ensure your environment meets these requirements:

- An existing **Amazon Bedrock Agent** with at least one **alias** configured.
- An IAM identity with permissions to call `bedrock:ListAgents`, `bedrock:DescribeAgent`, and `bedrock:InvokeModel`.
- The **Agent Toolkit for AWS** CLI installed locally (the `agents-build` skill validates these permissions automatically during the import phase).

## The Three-Phase Migration Workflow

The migration process follows a structured workflow defined in [`plugins/aws-agents/skills/agents-build/references/migrate.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-build/references/migrate.md). Each phase targets a specific aspect of the transition from declarative configuration to code-first implementation.

### Phase 1: Import the Bedrock Agent Definition

The import phase reads your existing Bedrock Agent configuration and generates a new AgentCore project structure.

Run the import command using the Agent Toolkit CLI:

```bash

# Replace <AGENT_ID> with your Bedrock Agent ARN or ID

agentcore create \
    --type import \
    --agent-id <AGENT_ID> \
    --framework strands

```

This command creates a directory containing a **Strands** project (or LangGraph if specified) that reproduces your original agent's behavior. The scaffolding includes:

- **Action groups** mapped to `src/tools/` with generated tool definitions.
- **Knowledge base bindings** in a `knowledge-base/` module if your original agent used Bedrock Knowledge Bases.
- **System prompts** that replicate the original agent's instructions.

### Phase 2: Integrate the New Runtime

After scaffolding, update your application to invoke the AgentCore runtime instead of the Bedrock Agent service.

Replace existing SDK calls that target `bedrockagent-runtime` with the new AgentCore client:

```javascript
import { AgentCoreClient } from "@aws-sdk/client-agentcore";

const client = new AgentCoreClient({ region: "us-east-1" });

async function askAgent(message) {
  const resp = await client.invokeAgent({
    agentId: "my-support-agent",
    input: { text: message },
  });
  console.log("Agent reply:", resp.output?.text);
}

```

The toolkit provides sample wrapper implementations in `src/runtime/` to simplify this transition.

### Phase 3: Validate and Cut Over

Complete the migration by testing the new implementation and retiring the legacy agent.

1. **Test the generated suite**: Run `npm test` or `pytest` to verify that each action group behaves as expected.
2. **Tune prompts**: Adjust the **system prompt** to handle format differences—Bedrock Agent wraps tool results in XML tags, while AgentCore uses JSON format.
3. **Deploy side-by-side**: Keep the original Bedrock Agent running temporarily as a safety net while you validate the AgentCore version.
4. **Retire the legacy agent**: Once confident, delete the Bedrock Agent via the console or `aws bedrock delete-agent` CLI command.

## Key Differences to Address During Migration

When migrating from Amazon Bedrock Agent to AWS AgentCore, you must account for fundamental architectural differences in how tool results are processed.

### Prompt Format Adjustments

Bedrock Agent automatically injects XML wrappers around tool results. AgentCore (specifically when using Strands or LangGraph) expects JSON-formatted tool outputs. Update your system prompts to reflect this change:

```python
SYSTEM_PROMPT = """
You are a helpful support assistant. When you call a tool, the tool will return a JSON
object. Use the following format for your response:

{
  "thoughts": "...",
  "action": "tool_name",
  "action_input": { ... }
}
"""

```

Place this prompt in [`src/prompts/system_prompt.py`](https://github.com/aws/agent-toolkit-for-aws/blob/main/src/prompts/system_prompt.py) (or the equivalent file generated during the import step).

### Orchestration Model Changes

The migration shifts from Bedrock's fixed orchestration patterns to configurable workflow engines. The `--framework strands` option (recommended) provides state-machine-based orchestration, while `--framework langgraph` offers graph-based execution flows.

## Why Migrate from Bedrock Agent to AgentCore?

Migrating to AWS AgentCore offers significant advantages for production deployments:

- **Extensibility**: AgentCore provides full access to the AWS SDK, custom libraries, and any language runtime, whereas Bedrock Agent limits you to declarative actions and Lambda orchestration.
- **Version Control**: AgentCore projects live in Git, enabling pull request reviews, CI/CD pipelines, and rollback capabilities. Bedrock Agent configuration resides primarily in the console.
- **Observability**: Integration with CloudWatch, X-Ray, and GenAI observability dashboards (via `plugins/aws-agents/skills/agents-harden`) exceeds the basic CloudWatch metrics available in Bedrock Agent.
- **Advanced Orchestration**: Support for Strands, LangGraph, or custom workflow engines enables complex state machines beyond Bedrock's fixed XML-based patterns.
- **Cost Control**: Fine-grained control over model invocations, token caching, and custom rate limiting compared to Bedrock's default pricing and throttling.

## Summary

Migrating from Amazon Bedrock Agent to AWS AgentCore transforms your agent from a console-managed configuration into a code-first project with enhanced capabilities:

- Use `agentcore create --type import` to scaffold a new project from existing Bedrock Agent definitions.
- Update client code to use `AgentCoreClient` instead of `bedrockagent-runtime` SDK calls.
- Adjust system prompts to handle JSON tool results instead of XML wrappers.
- Validate thoroughly using the generated test suites before retiring the legacy agent.
- Reference [`plugins/aws-agents/skills/agents-build/references/migrate.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-build/references/migrate.md) for detailed step-by-step guidance.

## Frequently Asked Questions

### What is AWS AgentCore and how does it differ from Amazon Bedrock Agent?

AWS AgentCore is a code-first runtime for building generative-AI agents that provides deeper integration with the AWS ecosystem, custom orchestration capabilities, and version control through Git. While Amazon Bedrock Agent offers a declarative, console-driven approach with fixed orchestration patterns, AgentCore allows developers to use frameworks like Strands or LangGraph for complex workflow logic and provides richer observability through CloudWatch and X-Ray integration.

### Do I need to rewrite all my action groups when migrating?

No, the migration process automatically converts your existing action groups. When you run `agentcore create --type import`, the toolkit reads your Bedrock Agent definition and generates corresponding tool definitions in `src/tools/` and knowledge base modules in `knowledge-base/`. However, you should review the generated code and test thoroughly, as you may need to adjust implementations for the JSON-based tool result format used by AgentCore.

### How do I handle the XML-to-JSON format change in prompts?

Bedrock Agent wraps tool results in XML tags, while AgentCore expects JSON objects. During migration, update your system prompts to explicitly instruct the model to expect JSON format. According to the migration guide in [`plugins/aws-agents/skills/agents-build/references/migrate.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-build/references/migrate.md), you should modify the generated prompt files (typically in `src/prompts/`) to specify JSON input/output formats and adjust any output parsers accordingly.

### Can I run both agents simultaneously during the migration?

Yes, running both agents side-by-side is a recommended safety practice. After deploying your new AgentCore runtime, keep the original Bedrock Agent active while you validate the new implementation. Once you've confirmed stable behavior through end-to-end testing and tuned any prompt differences, you can safely switch traffic fully to AgentCore and delete the legacy Bedrock Agent using the `aws bedrock delete-agent` CLI command or the AWS console.