Module ai.aws.bedrock.agentcore
ballerinax/ai.aws.bedrock.agentcore Ballerina library
Overview
This module runs a Ballerina agent on Amazon Bedrock AgentCore Runtime under the HTTP protocol contract.
The agentcore:Listener listens on 0.0.0.0:8080 and serves:
GET /ping, the health check, through the service'sget pingresourcePOST /invocations, the agent's entry point, through the service'spost invocationsresource
It reads the AgentCore request headers into an agentcore:Context and maps results and errors to JSON responses, so the service holds only agent logic.
Usage
import ballerina/http; import ballerinax/ai.aws.bedrock.agentcore; listener agentcore:Listener agentCoreListener = new; service on agentCoreListener { resource function get ping() returns agentcore:PingStatus => agentcore:HEALTHY; resource function post invocations(@http:Payload json payload, agentcore:Context ctx) returns json|error { return {response: "Hello"}; } }
The service must declare both resources, at the root base path. The compiler rejects any other resource or remote function.
get pingtakes no parameters and returnsagentcore:HEALTHY, oragentcore:HEALTHY_BUSYwhile the agent runs background work. AgentCore keeps aHealthyBusysession alive. The listener addstime_of_last_updateand changes it only when the status changes.post invocationscan declare an@http:Payloadparameter of ananydatatype a JSON body can hold, and anagentcore:Contextparameter, in any order. The compiler rejectsxml,tableandstring:RegExp, alone or in a union.
Payload
The request body is read as JSON and bound strictly to the declared type: a closed record rejects unknown fields. A byte[] parameter receives the raw body.
A string parameter expects a JSON string: curl -d '"hello"' binds hello, while curl -d hello is rejected with 400. An empty body binds to () when the type allows it. Error messages never echo the body.
Responses
- Any
anydataresult, including()and astring, is sent as200with a JSON body. - An
http:Responseor a status-code record such ashttp:Acceptedis sent as is. - An error is sent as
500with{"error": "Internal server error"}. A 4xxhttpscerrerror, such ashttpscerr:NotFoundError, keeps its status and message.
AgentCore shows the caller a 424 for any 4xx or 5xx from the agent, so the listener logs each error with its cause, request ID and session ID. Look for them in CloudWatch.
Context
agentcore:Context holds the session ID, a request ID, the workload access token, the OAuth2 callback URL, the inbound Authorization header, the allowlisted custom headers and the request headers. The listener never logs the token, Authorization, custom header values or the body.
AgentCore Runtime doesn't forward its request ID or runtime user ID headers to the container, so requestId is generated in practice and userId is always (). A caller can still set the request ID header, so never use requestId as a trust or isolation key. A call made with a runtime user ID arrives with a workload access token in workloadAccessToken instead.
Listener configuration
new agentcore:Listener() listens on 8080. Pass a port, or an http:Listener to share. The http:ListenerConfiguration fields apply, with defaults suited to AgentCore: a 900-second timeout (AgentCore allows 15-minute synchronous requests) and 96 KB of request headers.
A shared http:Listener keeps its own configuration. Give it timeout: 900 and requestLimits: {maxHeaderSize: 98304}, or the http defaults end agent turns longer than 60 seconds and reject requests with more than 8 KB of headers; the listener logs a warning when they are lower. Passing a configuration together with a shared http:Listener is an error, since it could never take effect.
Streaming responses, a custom invocation path and WebSocket are not supported yet.
See the AgentCore Runtime agent example for building, deploying and invoking an agent.