everruns-serve-agentcore

Run a serve app on Amazon Bedrock AgentCore Runtime. Imported as serve_agentcore.

Experimental. A hosting target for serve in the Everruns ecosystem. Like serve, it is a proof of concept with no compatibility promise.

AgentCore Runtime runs one container per session, each in its own microVM, and talks to it over HTTP on port 8080. This crate serves that contract around serve's host, so a serve app deploys to AgentCore unchanged.

What It Provides

Route	What it does
`GET /ping`	`{"status":"Healthy"}`, or `HealthyBusy` while a turn runs so AgentCore keeps the session alive
`POST /invocations`	An AG-UI 1.0 run of the app's agent as server-sent events. The body is AG-UI `RunAgentInput` (the AgentCore AG-UI protocol) or `{"prompt": "..."}` (a plain `InvokeAgentRuntime` call)
`GET /ws`	The same runs over AgentCore's WebSocket transport: each text message is one invocation body, and each AG-UI event comes back as one text message
`/health`, `/v1/...`	serve's own wire API, unchanged

The AG-UI thread defaults to the AgentCore session id (X-Amzn-Bedrock-AgentCore-Runtime-Session-Id), so one AgentCore session is one serve session.

Quick Example

use serve::prelude::*;

#[agent]
fn assistant() -> Agent {
    Agent::builder()
        .model("anthropic/claude-sonnet-5")
        .instructions("Be brief.")
        .build()
}

#[tokio::main]
async fn main() -> serve::Result {
    serve_agentcore::start(App::builder().discover().build()).await
}

With no command (what AgentCore runs) or agentcore, the binary serves the AgentCore contract on :8080 in serve's start mode. agentcore --dev uses dev mode to try it locally. Every other command (dev, start, eval, manifest, deploy) is serve's own.

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 serve keeps its SQLite session log. Default: the runtime's session storage at `/mnt/workspace/.serve` when mounted, else a temporary directory
`SERVE_WORKSPACE`	The agent's workspace. Default: `/mnt/workspace` when mounted
`SERVE_GATEWAY_URL`, `SERVE_GATEWAY_KEY`	serve's model gateway. An AgentCore Gateway inference endpoint (`https://<gateway>/inference/v1`) works here, with targets named after providers (`anthropic`, `openai`) so serve's `provider/model` ids route as-is
`AWS_REGION`, `AWS_DEFAULT_REGION`	Region for `bedrock/<model-id>` models (for example `bedrock/us.anthropic.claude-sonnet-4-6`). When set, those models call Amazon Bedrock directly with the runtime's execution role, ahead of the gateway. The role needs `bedrock:InvokeModelWithResponseStream`. Disable the default `bedrock` feature to drop the AWS SDK

AgentCore mounts session storage only when an invocation arrives, so /ping answers without touching storage and the server boots on the first other request.

Tools and sandbox

#[tool]s and MCP connections (including an AgentCore Gateway) work as in any serve app. With [sandbox] kind = "microvm", each agent gets a real shell and file tools in the session's workspace: the microVM is the isolation boundary. Under dev and eval the same setting falls back to the bashkit virtual shell.

AgentCore requires an arm64 Linux image. The agentcore example has a Dockerfile and deploy steps; the agentcore-workspace example adds the microVM shell, an approval tool and an @ag-ui/client script.

Limits

Not yet served: the MCP and A2A protocol ports.
ask_user and approvals park the turn without keeping the session busy, so AgentCore may stop the microVM after its idle timeout. With session storage the next microVM reopens the parked turn and its interrupt is still open, but an "always" answer from before the restart is not remembered, and a request a subagent parked is lost.
Not yet integrated: AgentCore Memory, Code Interpreter, Browser and Identity.
Schedules run in-process, which on AgentCore only fires while a session's microVM is up. Use EventBridge to call InvokeAgentRuntime instead.

Documentation

License

Licensed under the MIT License.

everruns-serve-agentcore 0.41.0