paigasus_helikon_runtime_agentcore/
lib.rs

1//! AWS Bedrock AgentCore runtime for Paigasus Helikon agents.
2//!
3//! [`AgentCoreServer`] mounts a single [`Agent`](paigasus_helikon_core::Agent) on an
4//! [`axum`] router that implements AWS Bedrock AgentCore's HTTP-protocol container
5//! contract:
6//!
7//! - **`GET /ping`** — a dedicated, always-responsive health-check handler that never
8//!   shares state with the runner, the agent, or any in-flight invocation, so a slow or
9//!   stuck invocation can never delay a health check. Returns HTTP 200 with a JSON body
10//!   of exactly `{"status":"Healthy"}` or `{"status":"HealthyBusy"}` — this casing is
11//!   part of the contract and is not configurable. An optional `time_of_last_update`
12//!   field (Unix seconds) is included *only* once a genuine status transition has
13//!   occurred: never on the initial steady state, and never re-stamped by a repeated
14//!   call reporting the same status, since AgentCore uses an advancing timestamp to
15//!   judge whether the agent is still making progress. See [`PingState`].
16//! - **`POST /invocations`** — the endpoint AgentCore calls to run the agent. Accepts
17//!   [`InvocationRequest`]'s three body shapes (`{"messages": [...]}`, `{"prompt": "..."}`,
18//!   `{"input": "..."}`). An optional
19//!   `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` request header (33-256 characters)
20//!   pins the invocation to a session via the configured
21//!   [`SessionProvider`](paigasus_helikon_runtime_axum::SessionProvider); an absent
22//!   header gets a fresh, unshared session (one microVM instance is, by AgentCore's
23//!   execution model, already one session). `Accept: application/json` selects a
24//!   buffered `200` response shaped `{"final_output": "...", "usage": {...}}`; any
25//!   other (or absent) `Accept` selects the default Server-Sent-Events transport,
26//!   emitting one `data: <AgentEvent JSON>` frame per event with a terminal
27//!   `RunCompleted`/`RunFailed` frame.
28//!
29//! [`AgentCoreServer::serve`] binds `0.0.0.0:8080` — the fixed port AgentCore's runtime
30//! contract expects — and logs the app-side cold-start latency (`"ready in {ms}ms"`)
31//! immediately after the listener is bound; AgentCore's own microVM provisioning
32//! latency is outside this crate's control and is not part of that measurement.
33//!
34//! Session and per-request context handling reuse `paigasus-helikon-runtime-axum`'s
35//! provider traits (`SessionProvider`/`ContextProvider`), so a self-hosted deployment
36//! and an AgentCore deployment of the same agent share one provider vocabulary.
37//!
38//! # MCP-protocol mode (feature `mcp`, default on)
39//!
40//! `AgentCoreServer::serve_mcp` serves the same configured agent as a single MCP
41//! tool over rmcp's streamable-HTTP transport instead of the HTTP-protocol contract
42//! above — for AgentCore's MCP runtime type rather than its default HTTP runtime
43//! type. It binds a separate port (`0.0.0.0:8000`) and mounts the MCP endpoint at
44//! `/mcp` plus a trivial `/ping` (not part of MCP; cheap insurance). See
45//! `AgentCoreServer::mcp_router` for the stateless/allowed-hosts configuration this
46//! requires and why.
47#![forbid(unsafe_code)]
48
49mod error;
50pub use error::AgentCoreError;
51
52mod invoke;
53pub use invoke::InvocationRequest;
54
55#[cfg(feature = "mcp")]
56mod mcp;
57
58mod ping;
59pub use ping::PingState;
60
61mod session;
62
63mod server;
64pub use server::{AgentCoreServer, AgentCoreServerBuilder};
paigasus_helikon_runtime_agentcore/lib.rs

paigasus_helikon_runtime_agentcore/
lib.rs
