Skip to main content

Adopt AgentCore with an Existing Agent

Who this is for

Developers migrating an existing agent—whether it uses Strands, LangGraph, CrewAI, another framework, or custom code—onto AgentCore Runtime. If you're building a new agent from scratch, see Build from CLI or First Agent (Console).

You already have a working agent and want to adopt AgentCore services without replacing its core reasoning loop. This page helps you choose an integration model, validate assumptions your agent makes about its environment, and prepare it for AgentCore Runtime.

Runtime gives each session an isolated microVM and uses active-resource consumption pricing; infrequently invoked agents can scale to zero after their sessions stop. Runtime can also export OpenTelemetry traces, but an existing agent may require framework instrumentation, ADOT dependencies, and CloudWatch configuration.

Start with your integration model​

This page focuses on two ways to expose existing agent logic to Runtime:

  • Use any agent framework — adapt a Python agent with BedrockAgentCoreApp and an @app.entrypoint handler, then deploy it with the AgentCore CLI.
  • Implement the Runtime HTTP contract — package a non-Python agent, existing HTTP application, or custom runtime as a container that exposes /invocations and /ping.

These are integration models, not your only infrastructure choices. After selecting one, compare the console, CLI, API, CloudFormation, CDK, and Terraform deployment methods.

If you are migrating from Bedrock Agents Classic, follow the Classic migration guide.

Choose your integration path​

Python SDK adapter — use this when your existing Python agent can be called from a handler function. BedrockAgentCoreApp handles the Runtime server contract while your decorated entrypoint translates the request into your framework's input and returns a serializable response. AWS provides examples for Strands, LangGraph, Google ADK, and OpenAI Agents, but the adapter pattern is not limited to those frameworks.

Custom protocol or container — use this for non-Python agents, existing HTTP services, custom process behavior, or direct control over the Runtime protocol and image. Your application implements the required endpoints and runs in an ARM64 container stored in Amazon ECR.

Many agents need only a thin entrypoint or protocol adapter, but deployment is not always change-free. Dependencies, environment configuration, authentication, asynchronous work, networking, filesystem use, and telemetry can all require updates.

What to validate before deployment​

  • Architecture and dependencies — confirm the application and any native libraries support linux/arm64.
  • Process contract — confirm the server starts without interactive input, binds to the required host and port, and reports health independently of long-running work.
  • Configuration and secrets — replace local profiles and developer credentials with environment configuration, AgentCore Identity, or a least-privilege Runtime execution role.
  • State and files — identify assumptions about local persistence and decide what belongs in session context, AgentCore Memory, S3 Files, EFS, or another durable store.
  • Concurrency and lifecycle — verify synchronous, asynchronous, streaming, and background operations behave correctly across session idle timeouts and maximum lifetimes.
  • Networking — classify dependencies as public endpoints or private VPC resources, then design routing, security groups, VPC endpoints, and NAT access accordingly.
  • Telemetry — confirm the framework emits the spans, metrics, and attributes you need, and configure their destination before relying on distributed traces.

Python SDK adapter: Strands example​

from strands import Agent
from strands_tools import file_read, file_write, editor

# Existing agent setup, abridged
agent = Agent(tools=[file_read, file_write, editor])

from bedrock_agentcore.runtime import BedrockAgentCoreApp
app = BedrockAgentCoreApp()

@app.entrypoint
def agent_invocation(payload, context):
    user_message = payload.get("prompt", "No prompt provided")
    result = agent(user_message)
    return {"result": result.message}

app.run()

Python SDK adapter: LangGraph example​

This excerpt assumes your existing code already creates and compiles graph.

from bedrock_agentcore.runtime import BedrockAgentCoreApp

# ... your existing nodes, edges, tools, and compiled graph ...
# graph = graph_builder.compile()

app = BedrockAgentCoreApp()

@app.entrypoint
def agent_invocation(payload, context):
    user_input = {
        "messages": [
            {"role": "user", "content": payload.get("prompt", "")}
        ]
    }
    output = graph.invoke(user_input)
    return {"result": output["messages"][-1].content}

app.run()

The pattern is the same for other Python frameworks: instantiate your existing agent, create a BedrockAgentCoreApp, translate the Runtime payload in an @app.entrypoint handler, and call app.run(). For complete dependencies and deployment configuration, see the official framework integration examples.

Validate custom-container compatibility​

Before deploying a custom container, verify that your agent's dependencies, runtime version, and process behavior satisfy the Runtime contract.

RequirementDetails
Platformlinux/arm64 (mandatory)
PortApplication must listen on 8080
HostMust bind to 0.0.0.0
/invocations endpointPOST — handles agent interactions (required)
/ping endpointGET — returns health status (required)
Image registryImage must be pushed to Amazon ECR

Runtime provisions an isolated CPU, memory, and filesystem environment for each session. When your agent needs private databases, internal APIs, or other VPC resources, configure Runtime VPC connectivity. For a VPC-mode runtime that also needs public internet access, use private subnets with a route to a NAT gateway and follow the Runtime network security practices.

Runtime makes temporary execution-role credentials available through the MicroVM Metadata Service (MMDS). Any code running in the microVM can request those credentials, so grant the execution role only the permissions the agent requires.

For implementation details, use these references:

Next steps​

warning

Everything produced by this tutorial is a prototype until you have applied the controls in Preparing for production. Do not use a prototype endpoint to serve real user traffic.