Deploy AI Agents to Amazon Bedrock AgentCore with GitHub Actions
What AgentCore Runtime gives an AI agent that a Lambda function does not, what your container must provide, and a complete GitHub Actions workflow that builds an ARM64 image, signs in to AWS without stored keys, updates the runtime and waits until the new version is ready.
Tecyfy · Published · Updated · 7 min read
Amazon Bedrock AgentCore Runtime is AWS's serverless host for AI agentsAgentA model that uses tools in a loop, deciding each next step from what the last one returned, until the task is done.: you give it a container, and it runs each user's session in its own small virtual machine for up to 8 hours. Deploying to it from GitHub Actions takes four steps: sign in to AWS with OpenID Connect (no stored keys), build an ARM64 image, push it to Amazon ECR, and call update-agent-runtime, which creates a new version of the agent. This guide explains what AgentCore adds and gives a workflow you can copy.
Why not just use Lambda?
An agent is not a normal request handler. It may call a model and tools dozens of times in one task, wait on slow APIs, and keep state between steps. That clashes with general-purpose serverless hosting:
| AWS Lambda | AgentCore Runtime | |
|---|---|---|
| Longest run | 15 minutes per standard function invocation per standard function invocation | 8 hours per session (14 days on Instances) |
| Isolation | Execution environments can be reused between requests | A dedicated microVM per user session, destroyed afterwards |
The session isolation matters most for agents that run code or browse: each session gets its own CPU, memory and filesystem, and the microVM is terminated and its memory sanitized afterwards, which helps keep one user's data out of another's session. AgentCore works with any framework (LangGraph, CrewAI, Strands or your own loop) and any model.
What your container must do
AgentCore runs your image if it keeps a short contract:
- Listen on
0.0.0.0, port 8080. - Answer
POST /invocationswith JSON, or stream with server-sent events. - Answer
GET /pingwith{"status": "Healthy"}(or"HealthyBusy"while it works in the background, which keeps the session alive). - Be built for ARM64. An image built on a normal x86 GitHub runner without a platform flag will not run.
AWS's bedrock-agentcore Python SDK provides both endpoints for you:
from bedrock_agentcore import BedrockAgentCoreApp
from my_agent import agent # your LangGraph, CrewAI or plain agent
app = BedrockAgentCoreApp()
@app.entrypoint
def invoke(payload):
return {"result": agent.run(payload["prompt"])}
if __name__ == "__main__":
app.run()
Sign in without stored keys
Do not put AWS access keys in GitHub secrets. With OpenID Connect, each workflow run gets a short-lived token from GitHub, which AWS exchanges for temporary credentials of one IAM role:
- In IAM, add
token.actions.githubusercontent.comas an OIDC identity provider. - Create a deployment role that trusts it, limited by the token's
subclaim to your repository and branch, for examplerepo:my-org/my-agent:environment:production, since the workflow below runs in theproductionenvironment (repositories created after July 15, 2026 use a sub with owner and repository IDs, such asrepo:my-org@123456/my-agent@456789:environment:production; match the format your repository uses). - Give the role only what deployment needs: push to the one ECR repository,
bedrock-agentcore:UpdateAgentRuntimeandGetAgentRuntimeon the one runtime, andiam:PassRolefor the agent's own execution role.
The agent's execution role (what the agent may do at run time, such as call Bedrock models) is separate from this deployment role. Keep them apart.
The workflow
Create the runtime once by hand or with infrastructure code; the workflow then ships each new version. It runs when agent code changes on main, or on demand:
name: Deploy agent
on:
push:
branches: [main]
paths: ["agent/**", "Dockerfile", "requirements.txt"]
workflow_dispatch:
permissions:
id-token: write # needed for OIDC
contents: read
env:
AWS_REGION: us-east-1
ECR_REPOSITORY: my-agent
jobs:
deploy:
runs-on: ubuntu-latest
environment: production # add required reviewers here if you want an approval step
steps:
- uses: actions/checkout@v7
- uses: aws-actions/configure-aws-credentials@v6
with:
role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
aws-region: ${{ env.AWS_REGION }}
- id: ecr
uses: aws-actions/amazon-ecr-login@v2
- uses: docker/setup-qemu-action@v4
- uses: docker/setup-buildx-action@v4
- name: Build and push an ARM64 image
uses: docker/build-push-action@v7
with:
context: .
platforms: linux/arm64
push: true
tags: ${{ steps.ecr.outputs.registry }}/${{ env.ECR_REPOSITORY }}:${{ github.sha }}
- name: Update the runtime
run: |
aws bedrock-agentcore-control update-agent-runtime \
--agent-runtime-id "${{ vars.AGENT_RUNTIME_ID }}" \
--agent-runtime-artifact '{"containerConfiguration":{"containerUri":"${{ steps.ecr.outputs.registry }}/${{ env.ECR_REPOSITORY }}:${{ github.sha }}"}}' \
--role-arn "${{ vars.AGENT_EXECUTION_ROLE_ARN }}" \
--network-configuration '{"networkMode":"PUBLIC"}'
- name: Wait until the new version is ready
run: |
for i in $(seq 1 60); do
status=$(aws bedrock-agentcore-control get-agent-runtime \
--agent-runtime-id "${{ vars.AGENT_RUNTIME_ID }}" --query status --output text)
echo "status: $status"
[ "$status" = "READY" ] && exit 0
[ "$status" = "UPDATE_FAILED" ] && exit 1
sleep 10
done
exit 1
Points worth knowing:
- Tag images with the commit, never only
latest. Each runtime version then points at an exact build, and you can tell what is running. - The ARM64 build runs under emulation on an x86 runner, which is slower. If your plan includes ARM64 GitHub runners, run the job on one and drop the QEMU step.
- IDs and role ARNs are not secrets; repository variables (
vars.) keep them visible and editable. - Scan the image. AWS's own example relies on Amazon Inspector scanning images as they arrive in ECR; turn on enhanced scanning for the repository.
Versions, endpoints and rolling back
Every update creates a new, immutable version of the runtime. The DEFAULT endpoint always moves to the newest one, so the workflow above is "deploy to latest". For a safer path, create a named endpoint such as production that stays on a chosen version: test the new version through DEFAULT, then move production to it with update-agent-runtime-endpoint. Rolling back is moving the endpoint back to the previous version, with no rebuild.
Before you move production, run a smoke test against the new version: a few fixed prompts whose answers or tool calls you can check. Agents fail in ways a build cannot catch, such as a tool whose arguments changed or a prompt that now loops, so the test should call the agent, not just its /ping.
Tecyfy Takeaway
- AgentCore Runtime hosts agents in a microVM per session for up to 8 hours, aligns CPU billing with active processing, which typically means no CPU charge while it waits on the model, and supports any framework and model.
- Your container listens on port 8080 with
/invocationsand/ping, and must be ARM64. - In GitHub Actions: OIDC to a narrow IAM role, build for
linux/arm64, push with the commit as the tag,update-agent-runtime, then wait forREADY. - Each update is a new immutable version; keep production on a named endpoint and move it only after a real test.
For the ideas behind what you are deploying, see Agentic WorkflowAgentic WorkflowA fixed sequence of model calls and tools that your code controls, such as classify, then look up, then draft. An agent decides its own next steps; a workflow follows the path you wrote. and our AI agents guide.
Questions
- What is Amazon Bedrock AgentCore Runtime?
- AWS's serverless host for AI agents. You give it a container, and it runs each user's session in its own small virtual machine for up to 8 hours, with CPU billing aligned to active processing, which typically means no CPU charge while it waits on the model.
- Why use AgentCore Runtime instead of AWS Lambda for an agent?
- A standard Lambda function invocation stops after 15 minutes (durable functions and Lambda MicroVMs run longer), can reuse execution environments between requests. AgentCore runs a session for up to 8 hours in a dedicated microVM destroyed afterwards, and adds identity, agent tracing and the MCP and A2A protocols.
- What must a container do to run on AgentCore Runtime?
- Listen on 0.0.0.0 port 8080, answer POST /invocations with JSON or server-sent events, answer GET /ping with a Healthy status, and be built for ARM64. The bedrock-agentcore Python SDK provides both endpoints.
- How do I deploy to AgentCore from GitHub Actions without storing AWS keys?
- Use OpenID Connect: add GitHub's token issuer as an identity provider in IAM and create a deployment role that trusts only your repository and its production environment. The workflow then assumes that role, builds a linux/arm64 image, pushes it to ECR and calls update-agent-runtime.
- How do I roll back an AgentCore agent?
- Every update creates a new immutable version. Keep production on a named endpoint, move it to a new version only after a smoke test, and roll back by moving the endpoint to the previous version, with no rebuild.
Sources
Where each fact comes from
- 1Host agent or tools with Amazon Bedrock AgentCore Runtime
- 2HTTP protocol contract
- 3AgentCore Runtime versioning and endpoints
- 4UpdateAgentRuntime
- 5Deploy AI agents on Amazon Bedrock AgentCore using GitHub Actions
- 6Configuring OpenID Connect in Amazon Web Services
- 7Lambda quotas
- 8Understanding the Lambda execution environment lifecycle
- 9Amazon Bedrock AgentCore Python SDK