Bedrock AgentCore
Protocol: REST-JSON
Endpoint: http://localhost:4566/runtimes/...
Emulates the Amazon Bedrock AgentCore control plane (bedrock-agentcore-control)
as a stateful local registry across runtimes, endpoints, gateways, memories, browser/code-interpreter
resources, credential providers, gateway rules, and resource policies. No real agent execution:
runtimes reach READY immediately and hold metadata only. See
the design note for scope and protocol details.
Supported Actions
| Action | Description |
|---|---|
CreateAgentRuntime |
Register an agent runtime; returns an id, versioned ARN, and workload identity |
ListAgentRuntimes |
List runtimes (paginated) |
GetAgentRuntime |
Get a runtime, optionally a specific version |
UpdateAgentRuntime |
Update a runtime; appends a new immutable version |
ListAgentRuntimeVersions |
List a runtime's versions (paginated) |
DeleteAgentRuntime |
Delete a runtime |
CreateAgentRuntimeEndpoint |
Creates a named runtime endpoint targeting an agent runtime version |
GetAgentRuntimeEndpoint |
Returns a runtime endpoint |
UpdateAgentRuntimeEndpoint |
Updates the target version or description of a runtime endpoint |
DeleteAgentRuntimeEndpoint |
Deletes a runtime endpoint |
ListAgentRuntimeEndpoints |
Lists runtime endpoints for an agent runtime |
CreateWorkloadIdentity |
Creates a workload identity |
GetWorkloadIdentity |
Returns a workload identity |
UpdateWorkloadIdentity |
Updates a workload identity |
DeleteWorkloadIdentity |
Deletes a workload identity |
ListWorkloadIdentities |
Lists workload identities |
CreateApiKeyCredentialProvider |
Creates an API key credential provider |
GetApiKeyCredentialProvider |
Returns an API key credential provider |
ListApiKeyCredentialProviders |
Lists API key credential providers |
UpdateApiKeyCredentialProvider |
Updates an API key credential provider |
DeleteApiKeyCredentialProvider |
Deletes an API key credential provider |
CreateOauth2CredentialProvider |
Creates an OAuth2 credential provider |
GetOauth2CredentialProvider |
Returns an OAuth2 credential provider |
ListOauth2CredentialProviders |
Lists OAuth2 credential providers |
UpdateOauth2CredentialProvider |
Updates an OAuth2 credential provider |
DeleteOauth2CredentialProvider |
Deletes an OAuth2 credential provider |
CreateGateway |
Creates a gateway |
GetGateway |
Returns a gateway |
UpdateGateway |
Updates a gateway |
DeleteGateway |
Deletes a gateway |
ListGateways |
Lists gateways |
CreateGatewayTarget |
Creates a target on a gateway |
GetGatewayTarget |
Returns a gateway target |
UpdateGatewayTarget |
Updates a gateway target |
DeleteGatewayTarget |
Deletes a gateway target |
ListGatewayTargets |
Lists targets on a gateway |
CreateMemory |
Creates a memory resource |
GetMemory |
Returns a memory resource |
UpdateMemory |
Updates a memory resource |
DeleteMemory |
Deletes a memory resource |
ListMemories |
Lists memory resources |
CreateEvent |
Appends an event to a memory. sessionId is optional and generated when omitted |
ListEvents |
Lists a session's events, newest first. POST to the session path, not GET |
GetEvent |
Returns one event |
DeleteEvent |
Deletes one event and echoes its id |
CreateBrowser |
Creates a custom browser |
GetCodeInterpreter |
Returns a custom or system code interpreter |
DeleteCodeInterpreter |
Deletes a custom code interpreter |
ListCodeInterpreters |
Lists custom and system code interpreters |
CreateCodeInterpreter |
Creates a custom code interpreter |
CreateBrowserProfile |
Creates a browser profile |
ListBrowserProfiles |
Lists browser profiles |
DeleteBrowserProfile |
Deletes a browser profile |
GetBrowserProfile |
Returns a browser profile |
GetBrowser |
Returns a custom or system browser |
DeleteBrowser |
Deletes a custom browser |
ListBrowsers |
Lists custom and system browsers |
CreateGatewayRule |
Creates a gateway rule |
GetGatewayRule |
Returns a gateway rule |
ListGatewayRules |
Lists rules on a gateway |
UpdateGatewayRule |
Updates a gateway rule |
DeleteGatewayRule |
Deletes a gateway rule |
GetResourcePolicy |
Returns the policy attached to an AgentCore resource |
PutResourcePolicy |
Creates or replaces a policy on an AgentCore resource |
DeleteResourcePolicy |
Deletes the policy attached to an AgentCore resource |
CreateHarness |
Creates a harness at version 1, filling in AWS's defaults; see Harnesses |
ListHarnesses |
Lists harnesses (paginated) |
GetHarness |
Returns a harness, optionally at a specific harnessVersion |
UpdateHarness |
Updates a harness; appends a new immutable version |
DeleteHarness |
Deletes a harness |
ListHarnessVersions |
Lists a harness's versions, newest first (paginated) |
A DEFAULT endpoint is created automatically with each runtime, and each runtime
is associated with an auto-created, resolvable workload identity.
Legacy agent/<uuid>:<version> runtime ARNs remain usable for invocation validation and tagging.
Legacy agentEndpoint/<uuid> endpoint IDs resolve for tagging and CloudFormation updates and deletes.
Responses use runtime/<agentRuntimeId> and runtime/<agentRuntimeId>/runtime-endpoint/<name>.
With runtime existence validation enabled, a harness runtime ARN is valid while its harness remains
registered; unknown and deleted runtime ARNs return ResourceNotFoundException.
Memory events
The event data plane is backed by real storage, so what a read returns is what was written rather than a fixed answer. Behaviour measured against real AgentCore:
- events come back newest first, and the event id embeds a zero-padded timestamp so ids sort chronologically as plain strings
includePayloads: falseomits thepayloadkey entirely rather than emptying itmaxResultsaccepts 1 to 100- a malformed memory id is a
ValidationException, while a well-formed but unknown one is aResourceNotFoundException. A memory id is a name followed by exactly ten alphanumerics - an unknown actor or session is an empty list, not an error
- a new event lands on the
mainbranch, and an empty payload is accepted, thoughpayloadis a required member: omitting it is aValidationExceptionwhile[]is valid CreateEventanswers201, not200ListEventspages withnextTokenand defaults to 20 events when a caller names nomaxResults
Memory records (extraction and retrieval) are not emulated: they depend on an extraction engine rather than on stored events.
Harnesses
Harness tags use the harness/<id> ARN. Tagging a harness runtime-environment ARN is not emulated.
A harness is stored with its configuration and settles in READY at once. No agent runtime is
started for it, and InvokeHarness does not read it.
harnessName(a letter, then up to 39 letters, digits and underscores) andexecutionRoleArnare required. The id is the name plus-and 10 alphanumerics, and a second harness with the same name in the Region is aConflictException. A repeatedclientTokenanswers the harness the first call created.- Members a request leaves out are filled in as AWS fills them:
apiFormatconverse_streamon abedrockModelConfig, emptysystemPrompt,tools,skills,allowedToolsandenvironmentVariables, and asliding_windowtruncation keeping 150 messages.memory,maxIterations,maxTokensandtimeoutSecondsare returned only when given. environment.agentCoreRuntimeEnvironmentnames the harness's runtimeharness_<name>, with an id and ARN that stay the same across updates, a 900-second idle session timeout and an 8-hour maximum lifetime unless given, andPUBLICnetworking.- Each
UpdateHarnessappends a version. A member the request carries replaces the current one;environmentArtifact,authorizerConfigurationandmemoryare set throughoptionalValue, and an empty wrapper removes them.GetHarness?harnessVersion=reads an earlier version. - An unknown harness is
ResourceNotFoundExceptionwith AWS's message, "Agent with name<id>not found.", and an unknown version "Version<n>not found for harness<id>". - Tags are set with
tagson create and through the shared/tags/{resourceArn}route.deleteManagedMemoryonDeleteHarnessis accepted and has no effect.
Data plane — InvokeAgentRuntime
POST /runtimes/{agentRuntimeArn}/invocations returns a fixed, configurable JSON
body (default {"output":"yes"}) and echoes the
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header. The request payload (opaque
binary, up to 100 MB) is never parsed. This operation returns a single non-streaming
200; InvokeHarness below is the streaming one.
Data plane — InvokeHarness
POST /harnesses/invoke returns an application/vnd.amazon.eventstream response, the same
framing ConverseStream uses, so an SDK client's stream iterator works unchanged. The frames
arrive in AWS's order: messageStart, contentBlockStart, one contentBlockDelta per chunk,
contentBlockStop, messageStop, metadata.
harnessArn, runtimeSessionId and messages are all required, and the first two are validated
against their modelled shapes rather than merely checked for presence: a harness ARN ends in the
same name-<10 alphanumerics> form AgentCore uses elsewhere, and a runtime session id is 33 to 100
characters. messages may be an empty array, but omitting the member is a ValidationException.
Note the wire bindings, which are easy to get wrong: harnessArn and qualifier are query
parameters, runtimeSessionId and runtimeUserId are headers
(X-Amzn-Bedrock-AgentCore-Runtime-Session-Id / -User-Id), and only messages, model,
tools and friends travel in the JSON body. A missing harnessArn or runtimeSessionId is a
ValidationException.
There is no agent loop and no model. The assistant's reply echoes the caller's last user
message, so a chat client visibly works end to end and a request that failed to parse is obvious
rather than hidden behind a fixed string. A request whose messages array is present but empty, or
carries no user turn, is legitimate and gets a canned reply rather than an error.
The harnessArn is not resolved against the harnesses created through the control
plane, so an application can invoke a harness it never created here. Tool execution, skills and multi-turn iteration are not emulated, so no tool-use
block is ever produced even when a request supplies tools.
Configuration
| Variable | Default | Description |
|---|---|---|
FLOCI_SERVICES_BEDROCK_AGENT_CORE_CONTROL_ENABLED |
true |
Enable/disable the control plane |
FLOCI_SERVICES_BEDROCK_AGENT_CORE_ENABLED |
true |
Enable/disable the data plane (invoke) |
FLOCI_SERVICES_BEDROCK_AGENT_CORE_INVOKE_RESPONSE |
{"output":"yes"} |
Canned InvokeAgentRuntime response body |
FLOCI_SERVICES_BEDROCK_AGENT_CORE_VALIDATE_RUNTIME_EXISTS |
false |
When true, InvokeAgentRuntime returns ResourceNotFoundException for an unknown runtime ARN instead of the canned response |
FLOCI_SERVICES_BEDROCK_AGENT_CORE_HARNESS_ECHO_PREFIX |
You said: |
Prefix on the reply InvokeHarness streams back |
FLOCI_SERVICES_BEDROCK_AGENT_CORE_HARNESS_EMPTY_REPLY |
No user message was supplied. |
Reply used when a request carries no user message |
Note on YAML config keys. The status endpoint reports these services as
bedrock-agentcore-controlandbedrock-agentcore, but the YAML property paths use hyphenated words:floci.services.bedrock-agent-core-control.enabledandfloci.services.bedrock-agent-core.enabled(and…bedrock-agent-core.invoke-response,…bedrock-agent-core.validate-runtime-exists,…bedrock-agent-core.harness-echo-prefix,…bedrock-agent-core.harness-empty-reply). TheFLOCI_*environment variables above map to these paths directly and are the recommended way to configure the service.
Behavior notes
agentRuntimeIdis<name>-<10 alphanumerics>; the runtime ARN isarn:<partition>:bedrock-agentcore:<region>:<account>:runtime/<agentRuntimeId>and stays the same across versions. Endpoint ARNs append/runtime-endpoint/<name>, includingDEFAULT.agentRuntimeNamemust match[a-zA-Z][a-zA-Z0-9_]{0,47}(no hyphens); invalid names returnValidationException.- Each
UpdateAgentRuntimeincrements the version and preserves prior versions forGetAgentRuntime?version=andListAgentRuntimeVersions. As on AWS, the new version holds exactly the configuration the request carries: an omitteddescription,authorizerConfiguration,protocolConfigurationorenvironmentVariablesis cleared on it rather than carried over from the previous version. networkConfiguration.networkModemust bePUBLICorVPCandprotocolConfiguration.serverProtocolmust beMCP,HTTP,A2AorAGUI; anything else returns the API'sValidationException.- Timestamps (
createdAt,lastUpdatedAt) are ISO-8601 strings. - Config blobs (
agentRuntimeArtifact,networkConfiguration, …) are otherwise stored opaquely and echoed back; they are not deeply validated. CreateMemorypersiststags,encryptionKeyArn, andmemoryExecutionRoleArn;UpdateMemoryappliesdescription,eventExpiryDuration, andmemoryExecutionRoleArn. As in AWS, memory tags are returned only byListTagsForResource, never embedded in thememoryresponse shape.
CloudFormation
Floci provisions these resource types:
AWS::BedrockAgentCore::RuntimeAWS::BedrockAgentCore::RuntimeEndpointAWS::BedrockAgentCore::Memory
Ref follows each registry schema's primaryIdentifier: the runtime's AgentRuntimeId, the
endpoint's AgentRuntimeEndpointArn and the memory's MemoryArn. Every read-only attribute the
schemas declare resolves through Fn::GetAtt, including the runtime's nested
WorkloadIdentityDetails.WorkloadIdentityArn; FailureReason is always empty because the
emulated resources never leave READY / ACTIVE. Nested configuration objects
(AgentRuntimeArtifact, NetworkConfiguration, AuthorizerConfiguration) are stored in the
API's camelCase shape, so GetAgentRuntime returns what the template declared; the template's
string ProtocolConfiguration becomes the API's {"serverProtocol": …}, and an omitted
NetworkConfiguration defaults to PUBLIC.
An update that keeps the create-only properties (the runtime's AgentRuntimeName, the endpoint's
AgentRuntimeId and Name, the memory's Name and EncryptionKeyArn) is applied in place with a
tag diff; a runtime whose declared configuration did not change keeps its version. The template is
the whole declared configuration: an optional property it no longer carries (a Description, the
runtime's AuthorizerConfiguration, ProtocolConfiguration or EnvironmentVariables, the
memory's MemoryExecutionRoleArn) is cleared on the resource. A member whose Fn::If selects
AWS::NoValue inside a nested configuration object is omitted. When a later resource fails the
stack update, an in-place change is rolled back onto the resource (a runtime as a further
version, as on AWS), and a provision that fails after its own change undoes it before the failure
propagates. Changing a create-only property creates a replacement and deletes the displaced
resource once the stack update commits, as on AWS. Deleting the stack deletes the resources.
Properties the emulated control plane has no model for are accepted and logged once at WARN
rather than failing the stack: the runtime's CapacityProviderConfiguration,
FilesystemConfigurations, LifecycleConfiguration, PlatformVersion and
RequestHeaderConfiguration; the endpoint's Tags; and the memory's MemoryStrategies,
IndexedKeys, NamespaceKeys and StreamDeliveryResources.
Examples
export AWS_ENDPOINT_URL=http://localhost:4566
# Create an agent runtime
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name myAgent \
--agent-runtime-artifact '{"containerConfiguration":{"containerUri":"public.ecr.aws/x/agent:latest"}}' \
--network-configuration '{"networkMode":"PUBLIC"}' \
--role-arn "arn:aws:iam::000000000000:role/agent-runtime" \
--endpoint-url $AWS_ENDPOINT_URL
# Get / list
aws bedrock-agentcore-control get-agent-runtime --agent-runtime-id <id> --endpoint-url $AWS_ENDPOINT_URL
aws bedrock-agentcore-control list-agent-runtimes --endpoint-url $AWS_ENDPOINT_URL
# Delete
aws bedrock-agentcore-control delete-agent-runtime --agent-runtime-id <id> --endpoint-url $AWS_ENDPOINT_URL