Serve on Amazon Bedrock AgentCore (experimental)
Deploy a serve app to Amazon Bedrock AgentCore Runtime with everruns-serve-agentcore: sessions on session storage, tools in the microVM, models via the Gateway.
Experimental. Like serve,
everruns-serve-agentcoreis a proof of concept with no compatibility promise.
Amazon Bedrock AgentCore Runtime
runs your agent container once per session, each copy in its own microVM, and
talks to it over HTTP on port 8080. everruns-serve-agentcore (imported as
serve_agentcore) serves that contract around a serve app,
so the same app runs under dev on a laptop and on AgentCore without changes.
How it maps
Section titled “How it maps”| AgentCore | serve |
|---|---|
Runtime session (X-Amzn-Bedrock-AgentCore-Runtime-Session-Id) |
One serve session: the AG-UI thread defaults to the session id |
POST /invocations |
An AG-UI 1.0 run of the app’s agent, streamed as server-sent events |
GET /ws (WebSocket) |
The same runs: each text message is one invocation body, each AG-UI event one text message back |
GET /ping |
Healthy, or HealthyBusy while a turn runs so AgentCore keeps the microVM up |
Session storage mount (/mnt/workspace) |
serve’s SQLite session log and the agent’s workspace |
| The session microVM | The sandbox: [sandbox] kind = "microvm" gives the agent a real shell |
| OpenAI-compatible Responses API endpoint | OPENAI_BASE_URL and OPENAI_API_KEY for openai/… models |
| Gateway MCP target | A #[connection] returning McpServer |
serve’s /v1 wire API and /health stay mounted next to the AgentCore routes.
Quickstart
Section titled “Quickstart”Start from any serve app and change main:
use serve::prelude::*;
#[tokio::main]async fn main() -> serve::Result { serve_agentcore::start(App::builder().discover().build()).await}[dependencies]everruns-serve = { version = "0.33", features = ["ag-ui"] }everruns-serve-agentcore = "0.33"With no command (what AgentCore runs) or agentcore, the binary serves the
AgentCore contract in serve’s start mode. Every other command (dev, start,
eval, manifest, deploy) is serve’s own.
Try the contract locally with the offline simulator:
cargo run -p serve-example-agentcore -- agentcore --dev
curl -s localhost:8080/ping# {"status":"Healthy"}
curl -N localhost:8080/invocations \ -H 'content-type: application/json' \ -H 'x-amzn-bedrock-agentcore-runtime-session-id: local-session-0000000000000000000000001' \ -d '{"prompt":"Where is order A-1001?"}'# data: {"type":"RUN_STARTED",...}# ...# data: {"type":"RUN_FINISHED",...}/invocations takes either an AG-UI RunAgentInput (what AgentCore’s AG-UI
protocol forwards from CopilotKit or @ag-ui/client) or {"prompt": "..."}
(a plain InvokeAgentRuntime call). Without a threadId and without the
session header, it answers 400 with a problem document.
Deploy
Section titled “Deploy”AgentCore runs linux/arm64 images on port 8080. The
agentcore example
has a distroless Dockerfile; build and push from the repository root:
docker buildx build --platform linux/arm64 \ -f examples/serve/agentcore/Dockerfile -t "$ECR_REPO:latest" --push .Create the runtime with the AG-UI protocol, session storage and an OpenAI key for the example’s model:
aws bedrock-agentcore-control create-agent-runtime \ --agent-runtime-name serve_agentcore_example \ --agent-runtime-artifact "containerConfiguration={containerUri=$ECR_REPO:latest}" \ --role-arn "$EXECUTION_ROLE_ARN" \ --network-configuration networkMode=PUBLIC \ --protocol-configuration serverProtocol=AGUI \ --filesystem-configurations '[{"sessionStorage":{"mountPath":"/mnt/workspace"}}]' \ --environment-variables "OPENAI_API_KEY=$OPENAI_API_KEY"Use serverProtocol=HTTP instead when callers send {"prompt": ...};
/invocations accepts both either way.
Invoke
Section titled “Invoke”From the CLI:
aws bedrock-agentcore invoke-agent-runtime \ --agent-runtime-arn "$AGENT_ARN" \ --runtime-session-id "$(uuidgen)-$(uuidgen)" \ --payload "$(echo -n '{"prompt":"Where is order A-1001?"}' | base64)" \ out.txt && cat out.txtFrom an AG-UI client, point HttpAgent at the runtime’s invocations URL and
send the session header, as the
workspace example’s client
does. It also shows the approval round trip: the first run ends with an
interrupt outcome, and the next run resumes it.
const agent = new HttpAgent({ url: `https://bedrock-agentcore.${region}.amazonaws.com/runtimes/${encodeURIComponent(agentArn)}/invocations?qualifier=DEFAULT`, headers: { Authorization: `Bearer ${token}`, "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": session, }, threadId: session,});Reuse a session id to return to the same microVM, conversation and workspace.
Over AgentCore’s WebSocket transport, connect to the runtime’s /ws URL
(wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<escaped-arn>/ws?qualifier=DEFAULT)
with the same session header, and send one invocation body per text message.
Each AG-UI event comes back as its own text message, ending with RUN_FINISHED
or RUN_ERROR; send the next body on the same socket for the next turn.
The upgrade request is authenticated like any other call: sign it with SigV4
(service bedrock-agentcore), either in the headers or, where the client cannot
set upgrade headers (a browser), as a presigned URL that also carries the
session id as the X-Amzn-Bedrock-AgentCore-Runtime-Session-Id query
parameter. The AWS SDKs have no WebSocket client, so sign the request yourself
and hand it to a WebSocket library; the
agentcore-workspace example
has a Python client (client/ws.py) that does both.
Persistence
Section titled “Persistence”AgentCore mounts session storage only when an invocation arrives, not while the
container initializes. So /ping never touches storage, and the server boots
on the first other request. It then picks, in order:
SERVE_DATA_DIR(or a SQLiteDATABASE_URL) when set. The workspace isSERVE_WORKSPACE, elseworkspace/under the data dir./mnt/workspacewhen it is mounted: the session log goes to/mnt/workspace/.serve, and the agent’s workspace is/mnt/workspace.- Otherwise a temporary directory, with a warning that nothing survives the microVM stopping.
With session storage, a conversation survives AgentCore stopping the microVM
after its idle timeout: the next invocation with the same session id resumes it
from the log. That includes a turn parked on an approval or an ask_user
question: on the new microVM the interrupt is still open, and the client’s
resume run answers it as before.
Session storage is an NFS mount that refuses POSIX file locks, so the binary
switches SQLite to dot-file locking (unix-dotfile) and rollback-journal mode
for the whole process, and clears lock files a stopped microVM left behind.
That is safe because one process owns a session’s storage.
Session storage is per session, kept for 14 days, and reset when
you deploy a new runtime version. For history across sessions and versions,
point DATABASE_URL at storage you own, such as an S3 Files or EFS mount
(both need VPC mode).
-
In-process tools.
#[tool]functions run in the container like anywhere else, includingneeds_approvaltools: over AG-UI the run ends with atool_approvalinterrupt and the client’s next run answers it. -
A real shell. With
[sandbox] kind = "microvm"inserve.toml, each agent getsbashand file tools in the session’s workspace, running directly in the container. The microVM is the isolation boundary, so there is no second sandbox inside it. Underdevandevalthe same setting uses the bashkit virtual shell, so local runs stay safe. Install whatever the agent should run (git, python, a compiler) in the image, as the workspace example Dockerfile does. -
AgentCore Gateway tools. A Gateway is an MCP server, so connect it like any other:
#[connection]fn gateway() -> McpServer {McpServer::http("https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp").auth(Secret::named("GATEWAY_TOKEN"))}startmode, which AgentCore runs, refuses to boot whenGATEWAY_TOKENis unset, so a misconfigured runtime fails its first invocation instead of running without tools.
Models
Section titled “Models”Name a Bedrock model as bedrock/<model-id>, where the rest is a Bedrock model
id or inference profile:
Agent::builder() .model("bedrock/us.anthropic.claude-sonnet-4-6")When AWS_REGION or AWS_DEFAULT_REGION is set, serve calls Amazon Bedrock
directly with the runtime’s execution role: no keys in the image or the
environment. Credentials come from the AWS default chain, which on AgentCore is
the execution role’s container credentials, and refresh before they expire.
The role needs bedrock:InvokeModelWithResponseStream on the model; for a
cross-region inference profile such as us.…, on the profile and on the
foundation model in each region it routes to. Pass the region in
--environment-variables if the runtime does not already provide it. This
route is serve’s bedrock feature, on by default in everruns-serve-agentcore;
default-features = false drops it and the AWS SDK.
For openai/<model> agents, set OPENAI_API_KEY; optional OPENAI_BASE_URL
selects a compatible Responses API endpoint. Serve strips only the first
openai/ prefix. An endpoint that expects target/model therefore needs an
agent model of openai/target/model. An endpoint that expects
openai/gpt-6.2-sol needs openai/openai/gpt-6.2-sol in the agent definition.
Configure the endpoint’s credential as OPENAI_API_KEY.
Without an explicit OpenAI URL/key pair, OPENROUTER_API_KEY routes
provider/model IDs unchanged through OpenRouter. An OpenAI endpoint override
does not reroute anthropic/… or bedrock/… models.
Configuration
Section titled “Configuration”| Variable | Meaning |
|---|---|
PORT |
Listen port, default 8080 (AgentCore requires 8080) |
SERVE_AGENTCORE_AGENT |
The agent /invocations runs, default the app’s default agent |
SERVE_DATA_DIR, DATABASE_URL |
Where the session log lives. Default: session storage when mounted |
SERVE_WORKSPACE |
The agent’s workspace. Default: the session storage mount |
OPENAI_API_KEY, OPENAI_BASE_URL |
Credential and optional Responses API endpoint for openai/… models |
AWS_REGION, AWS_DEFAULT_REGION |
Region for bedrock/<model-id> models, which run on the execution role |
Compared with other AgentCore agents
Section titled “Compared with other AgentCore agents”| serve-agentcore | Strands / bedrock-agentcore SDK |
|
|---|---|---|
/ping, /invocations, busy reporting |
Yes | Yes |
| AG-UI protocol | Yes, AG-UI 1.0 including interrupts | Yes |
/ws WebSocket |
Yes | Yes |
| MCP and A2A server protocols | Not yet | Yes |
| Conversation persistence | SQLite on session storage, including a turn parked on an approval or question | File or AgentCore Memory session managers |
| Long-term memory (AgentCore Memory) | Not yet | Yes |
| Gateway tools | MCP connection | MCP client |
| Shell and files | Built-in (sandbox = "microvm") |
Bring your own tools |
| Code Interpreter, Browser | Not yet | Client libraries |
| Identity (OAuth to third parties) | Secrets from the environment | @requires_access_token |
| Offline evals and simulator | Yes (eval, --dev) |
No |
Limits
Section titled “Limits”- Approvals and
ask_userquestions park a turn without keeping the microVM busy. AgentCore may stop the microVM while one waits; with session storage the next microVM asks it again, but an “always” answer given before the restart is not remembered after it, and a request a subagent parked is lost. #[schedule]s run in-process, so they only fire while a session’s microVM is up. Use EventBridge to callInvokeAgentRuntimeon a schedule instead.- Only
bedrock/…models use the runtime’s execution role. Other providers need the gateway or their own keys. The role must allowbedrock:InvokeModelWithResponseStream; a missing permission surfaces as anAccessDeniedExceptionon the first turn.