将多模型 AI Agent 迁移至 Amazon Bedrock AgentCore runtime

构建多模型智能体式 AI 应用的组织正面临日益增长的基础设施复杂性。为多种模型类型管理容器编排、扩缩容策略、身份和可观测性，会增加运营负担。团队往往花费更多时间在基础设施上，而非 Agent 逻辑开发。

在诸如 Amazon Elastic Container Service (Amazon ECS) 和 AWS Fargate 等自管理基础设施上运行 Agent 框架的开发者，对部署配置拥有完全控制权。随着智能体式工作负载不断演进和扩展，团队可能会选择采用提供内置会话管理、身份和可观测性的托管运行时。

Amazon Bedrock AgentCore 是一个可使用任意框架或模型来大规模构建、连接和优化 Agent 的平台。其托管部署能力 AgentCore runtime 负责容器生命周期、扩缩容、身份和可观测性，因此您可以专注于 Agent 代码。

在此前的文章 使用 Hugging Face smolagents 在 AWS 上构建多模型框架的智能体式 AI 中，我们展示了如何在自管理基础设施上构建具备多模型编排能力的医疗 AI Agent。本文将展示如何把该多模型 Agent 迁移至 Amazon Bedrock AgentCore runtime。此次迁移在保留三模型编排和向量增强知识检索等 Agent 能力的同时，减少了基础设施管理工作。

解决方案概述

本方案将一个多模型医疗 AI Agent 迁移至 Amazon Bedrock AgentCore runtime，同时保留既有 Agent 逻辑。该 Agent 在一个由 AgentCore 管理的容器内运行，通过向量增强知识检索处理跨三个模型后端的医疗查询。您可以将每个查询定向至最适合该任务的模型后端。部署在 Amazon SageMaker AI 上的领域专用模型，例如 BioM-ELECTRA-Large-SQuAD2，可处理专业生物医学查询；部署在 Amazon Bedrock 上的基础模型（FM），例如 Llama 3.1 70B Instruct by Meta，则可处理更广泛的医疗推理。该方法可帮助医疗团队应对不同类型的查询，同时降低管理底层基础设施的运营负担。

上一篇文章中的独立版本部署在 Amazon ECS 和 AWS Fargate 上，其中容器编排、扩缩容、身份和可观测性均由用户配置。AgentCore 版本则通过 AgentCore runtime 装饰器模式封装相同的 Agent 逻辑，并由 AgentCore runtime 自动处理这些运营事项。

Hugging Face smolagents 是一个开源 Python 库，旨在让开发者通过几行代码构建和运行 Agent。本方案使用 Hugging Face smolagents 框架作为参考实现，表明 AgentCore runtime 支持任意智能体框架。借助自带 Agent（bring-your-own，BYO Agent）方式，您可以将现有 Agent 代码部署到 AgentCore runtime，而无需重写代码或适配特定框架。

注意： 本方案是用于演示目的的示例实现。处理医疗或其他敏感查询的生产部署，应将 Amazon Bedrock Guardrails 用于内容过滤和事实依据验证，作为标准控制措施。

架构

该方案由以下服务和功能组成：

• Amazon Bedrock AgentCore runtime，用于 Agent 容器的托管部署、扩缩容、身份管理和可观测性。
• Amazon Bedrock 上的 Llama 3.1 70B Instruct by Meta，用于复杂医疗推理。有关不同 AWS 区域的模型可用性，请参阅 Amazon Bedrock 中按 AWS 区域支持的模型。
• Amazon SageMaker AI 上的 BioM-ELECTRA-Large-SQuAD2，用于专业生物医学查询和托管自动扩缩容。
• Amazon OpenSearch Service，用于通过医疗知识索引进行向量相似度匹配和上下文知识检索。
• 搭载 BioM-ELECTRA-Large-SQuAD2 的容器化模型服务器，用于自托管模型部署。
• AWS Identity and Access Management (IAM)，用于安全和访问控制。

注意： 上一篇文章（独立版本）使用 Claude 3.5 Sonnet V2 by Anthropic。本文使用 Llama 3.1 70B Instruct by Meta，以表明 AgentCore runtime 与模型无关。模型选择是实现层面的决策，而非硬性要求。

下图展示了解决方案架构，以及 Agent 如何在三个模型后端之间进行编排。

图 1：Amazon Bedrock AgentCore runtime 上的多模型医疗 Agent 架构

客户端 Web 界面连接至 Amazon Bedrock AgentCore runtime，后者托管医疗 Agent 容器。该容器使用带有 AgentCore runtime 装饰器的 Hugging Face smolagents 框架。AgentCore runtime 提供内置身份管理和可观测性。该 Agent 在三个模型后端之间进行编排：搭载 BioM-ELECTRA 的 Amazon SageMaker AI、搭载 Llama 3.1 70B Instruct by Meta 的 Amazon Bedrock，以及搭载 BioM-ELECTRA 的容器化模型服务器。该方案还包含 Amazon OpenSearch Service，用于向量增强知识检索。

该方案支持多种部署选项，每个后端均针对不同场景进行了优化：

1. Amazon SageMaker AI：使用来自 Hugging Face Hub 的模型，提供具备自动扩缩容能力的托管端点。
2. Amazon Bedrock：通过 AWS API 无服务器访问基础模型，并进行复杂推理。
3. 容器化模型服务器：用于自托管模型部署，以及来自 Hugging Face Hub 的工具集成（可部署在 Amazon ECS、Amazon Elastic Kubernetes Service (Amazon EKS) 或其他容器环境中）。

三个后端均实现了 Hugging Face Messages API 兼容性，无论选择何种模型服务，均可提供一致的请求和响应格式。

完整实现可在 sample-healthcare-agent-with-agentcore-on-aws GitHub 仓库中获取。

将 Agent 迁移至 AgentCore runtime

本节将介绍如何使用 AgentCore CLI，将现有医疗 AI Agent 迁移至 Amazon Bedrock AgentCore runtime。

前提条件

在部署该方案之前，您需要具备以下条件：

AgentCore runtime 概念

Amazon Bedrock AgentCore runtime 使用装饰器模式封装您的 Agent 逻辑。关键组件包括：

• BedrockAgentCoreApp – 初始化 AgentCore 应用。
• @app.entrypoint – 装饰 AgentCore runtime 在请求到达时调用的函数。
• app.run() – 启动 AgentCore runtime 服务器。

以下代码展示了 AgentCore 集成模式：

from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@app.entrypoint
def healthcare_agent_entrypoint(payload):
    user_input = payload.get("prompt", "")
    model_type = payload.get("model_type", "sagemaker")
    # Your existing agent logic here
    agent = TripleHealthcareAgent(vector_store=vector_store)
    response = agent.run(user_input, model_type=model_type)
    return str(response)

if __name__ == "__main__":
    app.run()

装饰器与 return 语句之间的 Agent 代码与独立版本保持不变。AgentCore runtime 会自动处理容器生命周期、扩缩容、身份和可观测性。

设置项目

创建一个 AgentCore 项目，并使用 AgentCore CLI 添加您的现有 Agent。

安装 AgentCore CLI：

npm install -g @aws/agentcore

创建新的 AgentCore 项目：

agentcore create --project-name healthcareagent --no-agent --build Container --language Python --protocol HTTP --model-provider Bedrock --memory none

将现有 Agent 作为自带（BYO）Agent 添加：

agentcore add agent --name healthcare_agentcore --type byo --build Container --language Python --protocol HTTP --network-mode PUBLIC --code-location ./agent-code --entrypoint healthcare_agentcore.py --framework Strands --model-provider Bedrock

注意： --framework 标志指定 CLI 模板。实际 Agent 代码使用 Hugging Face smolagents；无论模板选择如何，它都与 AgentCore runtime 兼容。

准备容器

1. 在 Agent 代码目录中创建 pyproject.toml 以定义依赖项：

   [project]
   name = "healthcare-agentcore"
   version = "1.0.0"
   requires-python = ">=3.10"
   dependencies = [
       "smolagents>=1.24.0",
       "transformers>=4.55.0",
       "boto3>=1.37.0",
       "opensearch-py>=3.1.0",
       "requests-aws4auth>=1.3.1",
       "bedrock-agentcore>=0.1.0",
       "numpy>=1.26.0",
       "requests>=2.32.0",
       "docker>=7.1.0",
   ]
   

2. 创建 Dockerfile：

   FROM public.ecr.aws/docker/library/python:3.12-slim
   RUN pip install --no-cache-dir uv
   WORKDIR /app
   COPY pyproject.toml ./
   RUN uv pip install --system -r pyproject.toml
   COPY . .
   EXPOSE 8080
   CMD ["python", "healthcare_agentcore.py"]
   

3. 创建 .dockerignore，以将镜像大小控制在 2 GB 限制以内：

   venv/
   .venv/
   __pycache__/
   .git/
   *.pyc
   

部署到 AgentCore runtime

完成项目配置后，您可以使用一条 CLI 命令部署 Agent。

部署 Agent：

CLI 会构建容器，将其推送至 Amazon Elastic Container Registry（Amazon ECR），并创建 AgentCore runtime Agent。部署大约需要 10–15 分钟。

测试已部署的 Agent

您可以通过两种方式测试已部署的 Agent：使用 AgentCore CLI，或使用 boto3 以编程方式进行测试。

使用 AgentCore CLI 调用 Agent：

agentcore invoke --prompt '{"prompt": "What are the side effects of metformin?", "model_type": "llama"}'

或者，使用 boto3 以编程方式调用：

该方式通过 boto3 SDK 直接调用与 CLI 相同的已部署 Agent。agentRuntimeArn 用于标识您已部署的 Agent，contentType 指定请求格式，payload 则承载提示词和模型选择。

import boto3, json

client = boto3.client('bedrock-agentcore', region_name='us-west-2')

payload = json.dumps({
    "prompt": "What are the side effects of metformin?",
    "model_type": "llama"
})

response = client.invoke_agent_runtime(
    agentRuntimeArn='<your-agent-runtime-arn>',
    contentType='application/json',
    accept='application/json',
    payload=payload.encode('utf-8')
)

result = response['response'].read().decode('utf-8')
print(result)

与自管理部署的主要差异

独立版本和 AgentCore runtime 版本以不同方式部署相同的 Agent。以下各节说明每种路径所提供的能力。

Amazon ECS 与 AWS Fargate 部署

独立版本运行在 Amazon ECS 和 AWS Fargate 上。您需要定义 ECS 任务定义和服务配置，设置自动扩缩容策略，为每个服务配置 IAM 角色，并通过 Amazon CloudWatch 设置可观测性。部署流程包括 Docker 构建、推送至 Amazon ECR，以及更新 ECS 服务。该路径可让您完全控制容器配置、网络和扩缩容行为。Agent 代码位于 healthcare_agentcore.py，与 Amazon Bedrock、Amazon SageMaker AI 及容器化后端集成，并使用 Amazon OpenSearch Service 进行向量搜索。

Amazon Bedrock AgentCore runtime 部署

AgentCore runtime 版本使用 AgentCore 装饰器模式运行相同的 healthcare_agentcore.py Agent 代码。AgentCore runtime 提供容器编排、基于会话的扩缩容、通过 IAM 集成进行的身份管理，以及通过内置追踪和日志实现的可观测性。部署仅需一条命令（agentcore deploy）。模型集成（Amazon Bedrock、Amazon SageMaker AI、容器化后端）和向量搜索（Amazon OpenSearch Service）则与独立版本保持一致。

两种部署方法各有不同优势。Amazon ECS 与 AWS Fargate 可完全控制容器配置、网络和扩缩容策略，适合拥有既有容器运维专业能力或特定基础设施要求的团队。Amazon Bedrock AgentCore runtime 则适合偏好托管基础设施、希望主要专注于 Agent 逻辑开发的团队。

无论采用哪种部署路径，以下要素

Organizations building multi-model agentic AI applications face growing infrastructure complexity. Managing container orchestration, scaling policies, identity, and observability for multiple model types adds operational overhead. Teams often spend more time on infrastructure than on agent logic development.

Developers running agentic frameworks on self-managed infrastructure such as Amazon Elastic Container Service (Amazon ECS) with AWS Fargate have full control over their deployment configuration. As agentic workloads evolve and scale, teams might choose to adopt managed runtimes that provide built-in session management, identity, and observability.

Amazon Bedrock AgentCore is a platform to build, connect, and optimize agents at scale, with any framework or model. AgentCore runtime, its managed deployment capability, handles container lifecycle, scaling, identity, and observability, so you can focus on your agent code.

In a previous post, Agentic AI with multi-model framework using Hugging Face smolagents on AWS, we showed how to build a healthcare AI agent with multi-model orchestration on self-managed infrastructure. In this post, we show you how to migrate that multi-model agent to Amazon Bedrock AgentCore runtime. The migration reduces infrastructure management while preserving agent capabilities, including triple-model orchestration and vector-enhanced knowledge retrieval.

Solution overview

This solution migrates a multi-model healthcare AI agent to Amazon Bedrock AgentCore runtime while preserving the existing agent logic. The agent processes medical queries across three model backends with vector-enhanced knowledge retrieval, all running inside a single AgentCore-managed container. You can direct each query to the model backend suited to the task. A domain-specific model such as BioM-ELECTRA-Large-SQuAD2 on Amazon SageMaker AI handles specialized biomedical queries, and a foundation model (FM) such as Llama 3.1 70B Instruct by Meta on Amazon Bedrock handles broader medical reasoning. This approach helps healthcare teams address a range of query types while reducing the operational overhead of managing the underlying infrastructure.

The standalone version from the previous post deployed on Amazon ECS with AWS Fargate includes container orchestration, scaling, identity, and observability configured by the user. The AgentCore version wraps the same agent logic with the AgentCore runtime decorator pattern, and AgentCore runtime handles these operational concerns automatically.

Hugging Face smolagents is an open source Python library designed to build and run agents using a few lines of code. This solution uses Hugging Face smolagents framework as a reference implementation, demonstrating that AgentCore runtime supports any agentic framework. With the bring-your-own (BYO) agent approach, you can deploy existing agent code to AgentCore runtime without rewriting or adapting to a specific framework.

Note: This solution is a sample implementation for demonstration purposes. Production deployments handling medical or other sensitive queries use Amazon Bedrock Guardrails for content filtering and grounding validation as a standard control.

Architecture

The solution consists of the following services and features:

• Amazon Bedrock AgentCore runtime for managed agent container deployment, scaling, identity, and observability.
• Amazon Bedrock with Llama 3.1 70B Instruct by Meta for complex medical reasoning. For model availability by AWS Region, refer to Supported models by AWS Region in Amazon Bedrock.
• Amazon SageMaker AI with BioM-ELECTRA-Large-SQuAD2 for specialized biomedical queries and managed auto scaling.
• Amazon OpenSearch Service for vector similarity matching and contextual knowledge retrieval with medical knowledge indexing.
• Containerized model server with BioM-ELECTRA-Large-SQuAD2 for self-hosted model deployment.
• AWS Identity and Access Management (IAM) for security and access control.

Note: The previous post (standalone version) uses Claude 3.5 Sonnet V2 by Anthropic. This post uses Llama 3.1 70B Instruct by Meta, demonstrating that AgentCore runtime is model-agnostic. The model choice is an implementation decision, not a requirement.

The following diagram illustrates the solution architecture and how the agent orchestrates across three model backends.

Figure 1: Multi-model healthcare agent architecture on Amazon Bedrock AgentCore runtime

A client web interface connects to Amazon Bedrock AgentCore runtime, which hosts the healthcare agent container. The container uses the Hugging Face smolagents framework with the AgentCore runtime decorator. AgentCore runtime provides built-in identity and observability. The agent orchestrates across three model backends: Amazon SageMaker AI with BioM-ELECTRA, Amazon Bedrock with Llama 3.1 70B Instruct by Meta, and a containerized model server with BioM-ELECTRA. The solution includes Amazon OpenSearch Service for vector-enhanced knowledge retrieval.

This solution supports deployment options with each backend optimized for different scenarios:

1. Amazon SageMaker AI for managed endpoints with auto scaling using Hugging Face Hub models.
2. Amazon Bedrock for serverless access to foundation models and complex reasoning through AWS APIs.
3. A containerized model server for self-hosted model deployment and tool integration from Hugging Face Hub (deployable on Amazon ECS, Amazon Elastic Kubernetes Service (Amazon EKS), or other container environments).

The three backends implement Hugging Face Messages API compatibility, providing consistent request and response formats regardless of the selected model service.

The complete implementation is available in the sample-healthcare-agent-with-agentcore-on-aws GitHub repository.

Migrate the agent to AgentCore runtime

This section walks through migrating the existing healthcare AI agent to Amazon Bedrock AgentCore runtime using the AgentCore CLI.

Prerequisites

Before you deploy the solution, you need the following:

AgentCore runtime concepts

Amazon Bedrock AgentCore runtime uses a decorator pattern to wrap your agent logic. The key components are:

• BedrockAgentCoreApp – initializes the AgentCore application.
• @app.entrypoint – decorates the function that AgentCore runtime calls when a request arrives.
• app.run() – starts the AgentCore runtime server.

The following code shows the AgentCore integration pattern:

from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@app.entrypoint
def healthcare_agent_entrypoint(payload):
    user_input = payload.get("prompt", "")
    model_type = payload.get("model_type", "sagemaker")
    # Your existing agent logic here
    agent = TripleHealthcareAgent(vector_store=vector_store)
    response = agent.run(user_input, model_type=model_type)
    return str(response)

if __name__ == "__main__":
    app.run()

The agent code between the decorator and return statement remains unchanged from the standalone version. AgentCore runtime handles container lifecycle, scaling, identity, and observability automatically.

Set up the project

Create an AgentCore project and add your existing agent using the AgentCore CLI.

Install the AgentCore CLI:

npm install -g @aws/agentcore

Create a new AgentCore project:

agentcore create --project-name healthcareagent --no-agent --build Container --language Python --protocol HTTP --model-provider Bedrock --memory none

Add your existing agent as a bring-your-own (BYO) agent:

agentcore add agent --name healthcare_agentcore --type byo --build Container --language Python --protocol HTTP --network-mode PUBLIC --code-location ./agent-code --entrypoint healthcare_agentcore.py --framework Strands --model-provider Bedrock

Note: The --framework flag specifies the CLI template. The actual agent code uses Hugging Face smolagents, which is compatible with AgentCore runtime regardless of the template selection.

Prepare the container

1. Create a pyproject.toml in your agent code directory to define dependencies:

   [project]
   name = "healthcare-agentcore"
   version = "1.0.0"
   requires-python = ">=3.10"
   dependencies = [
       "smolagents>=1.24.0",
       "transformers>=4.55.0",
       "boto3>=1.37.0",
       "opensearch-py>=3.1.0",
       "requests-aws4auth>=1.3.1",
       "bedrock-agentcore>=0.1.0",
       "numpy>=1.26.0",
       "requests>=2.32.0",
       "docker>=7.1.0",
   ]
   

2. Create a Dockerfile:

   FROM public.ecr.aws/docker/library/python:3.12-slim
   RUN pip install --no-cache-dir uv
   WORKDIR /app
   COPY pyproject.toml ./
   RUN uv pip install --system -r pyproject.toml
   COPY . .
   EXPOSE 8080
   CMD ["python", "healthcare_agentcore.py"]
   

3. Create a .dockerignore to keep the image size within the 2 GB limit:

   venv/
   .venv/
   __pycache__/
   .git/
   *.pyc
   

Deploy to AgentCore runtime

With the project configured, you can deploy the agent using a single CLI command.

Deploy the agent:

The CLI builds the container, pushes it to Amazon Elastic Container Registry (Amazon ECR), and creates the AgentCore runtime agent. Deployment takes approximately 10–15 minutes.

Test the deployed agent

You can test the deployed agent in two ways: using the AgentCore CLI or programmatically with boto3.

Invoke the agent using the AgentCore CLI:

agentcore invoke --prompt '{"prompt": "What are the side effects of metformin?", "model_type": "llama"}'

Or, invoke programmatically using boto3:

This path invokes the same deployed agent as the CLI, using the boto3 SDK directly. The agentRuntimeArn identifies your deployed agent, contentType specifies the request format, and payload carries the prompt and model selection.

import boto3, json

client = boto3.client('bedrock-agentcore', region_name='us-west-2')

payload = json.dumps({
    "prompt": "What are the side effects of metformin?",
    "model_type": "llama"
})

response = client.invoke_agent_runtime(
    agentRuntimeArn='<your-agent-runtime-arn>',
    contentType='application/json',
    accept='application/json',
    payload=payload.encode('utf-8')
)

result = response['response'].read().decode('utf-8')
print(result)

Key differences from self-managed deployment

The standalone version and the AgentCore runtime version deploy the same agent in different ways. The following sections describe what each path provides.

Amazon ECS with AWS Fargate deployment

The standalone version runs on Amazon ECS with AWS Fargate. You define ECS task definitions and service configuration, set auto scaling policies, configure IAM roles per service, and set up observability through Amazon CloudWatch. Deployment uses a Docker build, an Amazon ECR push, and an ECS service update. This path gives you full control over container configuration, networking, and scaling behavior. The agent code lives in healthcare_agentcore.py, integrates with Amazon Bedrock, Amazon SageMaker AI, and the containerized backend, and uses Amazon OpenSearch Service for vector search.

Amazon Bedrock AgentCore runtime deployment

The AgentCore runtime version runs the same healthcare_agentcore.py agent code with the AgentCore decorator pattern. AgentCore runtime provides container orchestration, session-based scaling, identity management through IAM integration, and observability through built-in tracing and logging. Deployment uses a single command (agentcore deploy). The model integration (Amazon Bedrock, Amazon SageMaker AI, containerized backend) and vector search (Amazon OpenSearch Service) remain the same as the standalone version.

Both deployment approaches have distinct advantages. Amazon ECS with AWS Fargate provides full control over container configuration, networking, and scaling policies, suitable for teams with existing container operations expertise or specific infrastructure requirements. Amazon Bedrock AgentCore runtime is suited for teams that prefer managed infrastructure and want to focus primarily on agent logic development.

Regardless of the deployment path, the following elements remain unchanged when migrating from the standalone version to AgentCore runtime:

• Core agent logic (BedrockAgentCoreApp decorator + existing code).
• Multi-model orchestration across Amazon Bedrock, Amazon SageMaker AI, and containerized backends.
• Vector-enhanced knowledge retrieval with Amazon OpenSearch Service.
• Hugging Face Messages API compatibility across model backends.

Clean up

To avoid incurring future charges, delete the resources you created when you no longer need them. If you plan to continue using the deployed agent, no action is required.

1. **Remove the AgentCore runtime agent:
   ** First, remove all resources from your local configuration:

Then deploy again to tear down the AWS resources:

2. Delete the Amazon SageMaker AI endpoint:

   aws sagemaker delete-endpoint --endpoint-name healthcare-agentcore-endpoint-1 --region us-west-2
   

3. Delete the Amazon OpenSearch Service domain:

   aws opensearch delete-domain --domain-name healthcare-vector-store --region us-west-2
   

Conclusion

In this post, we showed how to migrate a multi-model healthcare AI agent from self-managed Amazon ECS with AWS Fargate infrastructure to Amazon Bedrock AgentCore runtime. The migration required no changes to the core agent logic. The same healthcare_agentcore.py file orchestrates across Amazon Bedrock, Amazon SageMaker AI, and a containerized model server. It runs on AgentCore runtime with the addition of the AgentCore decorator pattern (BedrockAgentCoreApp, @app.entrypoint, and app.run()). For healthcare teams, this pattern directs specialized biomedical queries to a domain-specific model such as BioM-ELECTRA-Large-SQuAD2 on Amazon SageMaker AI. It routes broader medical reasoning to a foundation model such as Llama 3.1 70B Instruct by Meta on Amazon Bedrock. Together, these backends support a range of query types.

For teams that choose managed infrastructure, AgentCore runtime handles container orchestration, scaling, identity management, and observability. You can focus on agent logic development instead. The framework-agnostic design supports a wide combination of models and agentic frameworks, making this migration pattern applicable across industries including healthcare, financial services, and manufacturing.

To get started, clone the sample-healthcare-agent-with-agentcore-on-aws GitHub repository and follow the deployment steps in this post. To understand the standalone implementation that this post migrates from, see Agentic AI with multi-model framework using Hugging Face smolagents on AWS. If there are questions about getting started with Amazon Bedrock AgentCore, speak with an AWS generative AI Specialist.

Further reading

---

About the author

Sanhita Sarkar

Sanhita Sarkar, PhD, drives global AI/ML and generative AI partner solutions at AWS. She brings extensive leadership experience across edge, cloud, and data center environments, holds several patents, has published research papers, and serves as chair for technical conferences.