Deploy AI agents on Amazon Bedrock AgentCore using GitHub Actions

Recently, AWS announced Amazon Bedrock AgentCore, a flexible service that helps developers seamlessly create and manage AI agents across different frameworks and models, whether hosted on Amazon Bedrock or other environments. Specifically, AgentCore Runtime provides a secure, serverless, and purpose-built hosting environment for deploying and running AI agents or tools. AgentCore Runtime is framework agnostic, working seamlessly with popular frameworks like LangGraph, Strands, and CrewAI for deploying your AI agents and tools with automatic scaling and built-in security.

In this post, we demonstrate how to use a GitHub Actions workflow to automate the deployment of AI agents on AgentCore Runtime. This approach delivers a scalable solution with enterprise-level security controls, providing complete continuous integration and delivery (CI/CD) automation. By implementing a comprehensive pipeline, we enable seamless agent deployment with AWS best practices, including OpenID Connect (OIDC) authentication, least-privilege access controls, and environment separation. Our solution facilitates efficient updates for existing agents and integrates continuous security scans and rigorous code quality checks. The result is a robust deployment strategy that helps minimize operational complexity, enhance security, and accelerate AI agent development across enterprise environments.

Benefits of Amazon Bedrock AgentCore Runtime

AgentCore Runtime is the ideal service for production agent deployments:

• Provides a framework agnostic environment to run your agents
• Works with large language models (LLMs) such as models offered by Amazon Bedrock and Anthropic Claude
• Provides session isolation by running each user session in a dedicated microVM with isolated CPU, memory, and file system resources
• Supports both real-time interactions and long-running workloads up to 8 hours
• Offers built-in capabilities for authentication and observability

Solution overview

We’ve developed a comprehensive CI/CD pipeline with GitHub Actions that streamlines the deployment of Agents in compliance with security standard. The pipeline is available as a ready-to-use solution that can integrate seamlessly with your existing development workflow.The solution consists of the following key components:

• GitHub Actions – A workflow orchestration tool to host the pipeline
• Amazon Bedrock AgentCore Runtime – An AWS service to host and run the deployed agents
• Amazon Elastic Container Registry (Amazon ECR) – An AWS service to store, manage, and deploy container images for agents
• Amazon Inspector – An AWS service to perform advanced and continuous vulnerability scanning on container images
• IAM OIDC identity provider – A federated authentication service to establish trust between GitHub and AWS to allow GitHub Actions to deploy on AWS without maintaining AWS secrets and credentials

The following diagram illustrates the architecture for the solution.

The data flow consists of the following steps:

1. A developer commits code changes from their local repository to the GitHub repository. In this solution, the GitHub Action is triggered manually, but this can be automated.
2. The GitHub Action triggers the build stage.
3. GitHub’s OIDC uses tokens to authenticate with AWS and access resources.
4. GitHub Actions invokes the command to build and push the agent container image to Amazon ECR directly from the Dockerfile.
5. AWS Inspector triggers an advanced security scan when the image is uploaded.
6. An AgentCore Runtime instance is created using the container image.
7. The agent can further query the Amazon Bedrock model and invoke tools according to its configuration.

In the following sections, we walk through the steps to deploy the solution:

1. Download the source code from the GitHub repo.
2. Create your agent code.
3. Set up GitHub secrets.
4. Create an IAM role and policies.
5. Create the GitHub Actions workflow.
6. Trigger and monitor the pipeline.
7. Verify the deployment.

Prerequisites

Before you can use our secure CI/CD pipeline for deploying agents to AgentCore Runtime, verify you have the following prerequisites in place:

• An AWS account with sufficient permissions to create IAM Identity and Access Management (IAM) roles
• Access to the required LLM model from the supported foundation models in Amazon Bedrock
• GitHub account with Actions enabled (GitHub.com or GitHub Enterprise)
• Python 3.10+ for local development and testing

Download source code

Clone the source code repository: bedrock-agentcore-runtime-cicd

git clone https://github.com/aws-samples/sample-bedrock-agentcore-runtime-cicd.git

The repository folder consists of the following structure:

bedrock-agentcore-runtime-cicd/
├── .github/
│   └── workflows/
│       └── deploy-agentcore.yml         # file contains the set of action to build and deploy the agent on AgentCore Runtime
│       └── test-agent.yml               # after deployment this file is used to test agent via manual workflow dispatch
├── agents/
│   ├── strands_agent.py                 # uses BedrockAgentCoreApp app that creates an AI agent using the Strands framework with Claude as the underlying model
│   ├── requirements.txt                 # contains dependencies 
├── scripts
│   ├── create_iam_role.py               # IAM role required for Bedrock AgentCore Runtime
│   ├── deploy_agent.py                  # deploys a custom agent to AWS Bedrock's AgentCore Runtime platform, which allows you to run containerized AI agents on AWS infrastructure 
│   └── setup_oidc.py                    # OIDC setup for Github Authentication and Authorization to access AWS account to deploy required services
│   └── cleanup_ecr.py                   # keeps 9 recent images in ECR registry, can be customized
│   └── create_guardrail.py              # setup minimum guardrail for content filtering, can be customized according to use case
│   └── test_agent.py                    # contains test cases
└── Dockerfile                           # contain instructions to build Docker image
└── README.md

Create agent code

Create your agent with the framework of your choice using the AgentCore Runtime toolkit. The toolkit uses BedrockAgentCoreApp to create an application that provides a standardized way to package your AI agent code into a container that can run on AgentCore Runtime managed infrastructure. It also uses app.entrypoint, a Python decorator that marks a function as the main entry point. When the Amazon Bedrock agent receives the incoming API request, this function receives and processes the user’s request. In this sample agent code, when someone calls your Amazon Bedrock agent using an API, AgentCore Runtime will automatically call the strands_agent_bedrock(payload) function.

In this post, we use the agents/strands_agent.py file to create an agent using the Strands Agents framework:

"""
This module defines a conversational AI agent that can perform calculations
using the Strands framework.
"""
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent
from strands.models import BedrockModel
from strands_tools import calculator
# Initialize the Bedrock AgentCore application
app = BedrockAgentCoreApp()
# Configure the Claude model for the agent with guardrail
model_id = "us.anthropic.claude-sonnet-4-20250514-v1:0"
# Load guardrail ID if available
guardrail_config = None
try:
    with open("guardrail_id.txt", "r", encoding="utf-8") as f:
        guardrail_id = f.read().strip()
        if guardrail_id:
            guardrail_config = {
                "guardrailIdentifier": guardrail_id,
                "guardrailVersion": "1",
            }
            print(f"Loaded guardrail: {guardrail_id}")
except FileNotFoundError:
    print("No guardrail file found - running without guardrail")
model = BedrockModel(model_id=model_id, guardrail=guardrail_config)
# Create the agent with tools and system prompt
agent = Agent(
    model=model,
    tools=[calculator],
    system_prompt="You're a helpful assistant. You can do simple math calculation.",
)
@app.entrypoint
def strands_agent_bedrock(payload):
    """
    Main entrypoint for the Bedrock AgentCore Runtime.
    This function is called by AWS Bedrock AgentCore when the agent receives
    a request. It processes the user input and returns the agent's response.
    Args:
        payload (dict): Request payload containing user input
                       Expected format: {"prompt": "user question"}
    Returns:
        str: The agent's text response to the user's prompt
    """
    # Extract the user's prompt from the payload
    user_input = payload.get("prompt")
    # Process the input through the agent (handles tool selection and model inference)
    response = agent(user_input)
    # Extract and return the text content from the response
    return response.message["content"][0]["text"]
if __name__ == "__main__":
    # Run the application locally for testing
    # In production, this is handled by Bedrock AgentCore Runtime
    app.run()

Set up GitHub secrets

The GitHub Actions workflow must access resources in your AWS account. In this post, we use an IAM OpenID Connect identity provider and IAM roles with IAM policies to access AWS resources. OIDC lets your GitHub Actions workflows access resources in AWS without needing to store the AWS credentials as long-lived GitHub secrets. These credentials are stored as GitHub secrets within your GitHub repository Settings under Secrets option. For more information, see Using secrets in GitHub Actions.

Create IAM roles and policies

To run agents or tools in AgentCore Runtime, you need an IAM execution role. For information about creating an IAM role, see IAM role creation.

In this post, we create the required trust policy and execution role for AgentCore Runtime. See IAM Permissions for AgentCore Runtime for more details.

The following code is for the AgentCore Runtime trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AssumeRolePolicy",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
            "StringEquals": {
                "aws:SourceAccount": "accountId"
            },
            "ArnLike": {
                "aws:SourceArn": "arn:aws:bedrock-agentcore:region:accountId:*"
            }
       }
    }
  ]
}

The following code is for the AgentCore Runtime execution role:

{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "bedrock:InvokeModel",
                    "bedrock:InvokeModelWithResponseStream",
                    "bedrock:Converse",
                    "bedrock:ConverseStream"
                ],
                "Resource": [
                    "arn:aws:bedrock:*::foundation-model/us.anthropic.claude-sonnet-4-*",
                    "arn:aws:bedrock:*::foundation-model/anthropic.claude-*",
                    "arn:aws:bedrock:*:*:inference-profile/us.anthropic.claude-sonnet-4-*",
                    "arn:aws:bedrock:*:*:inference-profile/anthropic.claude-*"
                ]
            },
            {
                "Effect": "Allow",
                "Action": [
                    "ecr:GetAuthorizationToken",
                    "ecr:BatchCheckLayerAvailability",
                    "ecr:GetDownloadUrlForLayer",
                    "ecr:BatchGetImage"
                ],
                "Resource": "arn:aws:ecr:::repository/bedrock-agentcore-*"
            },
            {
                "Effect": "Allow",
                "Action": [
                    "logs:CreateLogGroup",
                    "logs:CreateLogStream",
                    "logs:PutLogEvents"
                ],
                "Resource": "arn:aws:logs:*:*:*"
            }
        ]
    }

Create the GitHub Actions workflow

Refer the CI/CD workflow file at .github/workflows/deploy-agentcore.yml for details to create the workflow.The following steps will be performed by the workflow:

• It uses the default Ubuntu Github Runner for the task provided in the pipeline.
• The workflow installs the required dependencies mentioned in the requirement.txt file.
• It builds the Docker image and deploys it on the ECR repository.
• The image is scanned with Amazon Inspector to identify potential vulnerabilities.
• AgentCore Runtime deploys the agent as an endpoint.
• The workflow tests the agent endpoint to verify functionality.

Trigger and monitor pipeline

This pipeline can be triggered either by changing a code in the agents folder or manually using the workflow dispatch option. This might further change according to your organization’s branching strategy. Update the code in .github/workflows/deploy-agentcore.yml to change this trigger behavior.

Test agent

After the agent is deployed, we will verify its functionality by triggering the Test Agent workflow manually via workflow dispatch option.

AgentCore Runtime versioning and endpoints

Amazon Bedrock AgentCore implements automatic versioning for AgentCore Runtime and lets you manage different configurations using endpoints. Endpoints provide a way to reference specific versions of AgentCore Runtime. For more details and sample code, see AgentCore Runtime versioning and endpoints.

Clean up

To avoid incurring future charges, complete the following steps:

1. Delete the ECR images from the Amazon ECR console created through the deployment using GitHub Actions.
2. Delete the agent deployed in AgentCore Runtime.

Conclusion

In this post, we demonstrated a comprehensive approach to using GitHub Actions for a more secure and scalable deployment of AI agents on AgentCore Runtime. Our solution provides a robust, automated, and controlled environment for generative AI applications, addressing critical enterprise deployment challenges by automating dependency management, implementing continuous code quality checks, performing comprehensive vulnerability scanning, and facilitating consistent deployment processes. By abstracting infrastructure complexities, this pipeline helps developers focus on agent logic and functionality, while providing a framework-agnostic approach that supports seamless management of multiple AI agents at scale. As AI agents continue to transform enterprise capabilities, this solution represents a significant step towards streamlining AI agent development and operational management, offering a standardized, secure, and efficient deployment mechanism for modern generative AI applications.

As a next step, you can use Amazon Q to intelligently enhance and customize your AI agent deployment pipeline, transforming your CI/CD processes with advanced, context-aware automation.

About the authors

Prafful Gupta is an Assoc. Delivery Consultant at AWS based in Gurugram, India. Having started his professional journey with Amazon a year ago, he specializes in DevOps and Generative AI solutions, helping customers navigate their cloud transformation journeys. Beyond work, he enjoys networking with fellow professionals and spending quality time with family. Connect on LinkedIn at: linkedin.com/in/praffulgupta11/

Anshu Bathla is a Lead Consultant – SRC at AWS, based in Gurugram, India. He works with customers across diverse verticals to help strengthen their security infrastructure and achieve their security goals. Outside of work, Anshu enjoys reading books and gardening at his home garden. Connect on LinkedIn at: linkedin.com/in/anshu-bathla/