Skip to content
Docs
GitHub

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.

8 min readEdit on GitHub

Experimental. Like serve, everruns-serve-agentcore is 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.

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.

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:

Terminal window
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.

AgentCore runs linux/arm64 images on port 8080. The agentcore example has a distroless Dockerfile; build and push from the repository root:

Terminal window
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:

Terminal window
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.

From the CLI:

Terminal window
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.txt

From 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.

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:

  1. SERVE_DATA_DIR (or a SQLite DATABASE_URL) when set. The workspace is SERVE_WORKSPACE, else workspace/ under the data dir.
  2. /mnt/workspace when it is mounted: the session log goes to /mnt/workspace/.serve, and the agent’s workspace is /mnt/workspace.
  3. 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, including needs_approval tools: over AG-UI the run ends with a tool_approval interrupt and the client’s next run answers it.

  • A real shell. With [sandbox] kind = "microvm" in serve.toml, each agent gets bash and 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. Under dev and eval the 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"))
    }

    start mode, which AgentCore runs, refuses to boot when GATEWAY_TOKEN is unset, so a misconfigured runtime fails its first invocation instead of running without tools.

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.

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
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
  • Approvals and ask_user questions 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 call InvokeAgentRuntime on a schedule instead.
  • Only bedrock/… models use the runtime’s execution role. Other providers need the gateway or their own keys. The role must allow bedrock:InvokeModelWithResponseStream; a missing permission surfaces as an AccessDeniedException on the first turn.