Skip to content

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: false omits the payload key entirely rather than emptying it
  • maxResults accepts 1 to 100
  • a malformed memory id is a ValidationException, while a well-formed but unknown one is a ResourceNotFoundException. 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 main branch, and an empty payload is accepted, though payload is a required member: omitting it is a ValidationException while [] is valid
  • CreateEvent answers 201, not 200
  • ListEvents pages with nextToken and defaults to 20 events when a caller names no maxResults

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) and executionRoleArn are required. The id is the name plus - and 10 alphanumerics, and a second harness with the same name in the Region is a ConflictException. A repeated clientToken answers the harness the first call created.
  • Members a request leaves out are filled in as AWS fills them: apiFormat converse_stream on a bedrockModelConfig, empty systemPrompt, tools, skills, allowedTools and environmentVariables, and a sliding_window truncation keeping 150 messages. memory, maxIterations, maxTokens and timeoutSeconds are returned only when given.
  • environment.agentCoreRuntimeEnvironment names the harness's runtime harness_<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, and PUBLIC networking.
  • Each UpdateHarness appends a version. A member the request carries replaces the current one; environmentArtifact, authorizerConfiguration and memory are set through optionalValue, and an empty wrapper removes them. GetHarness?harnessVersion= reads an earlier version.
  • An unknown harness is ResourceNotFoundException with AWS's message, "Agent with name <id> not found.", and an unknown version "Version <n> not found for harness <id>".
  • Tags are set with tags on create and through the shared /tags/{resourceArn} route. deleteManagedMemory on DeleteHarness is 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-control and bedrock-agentcore, but the YAML property paths use hyphenated words: floci.services.bedrock-agent-core-control.enabled and floci.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). The FLOCI_* environment variables above map to these paths directly and are the recommended way to configure the service.

Behavior notes

  • agentRuntimeId is <name>-<10 alphanumerics>; the runtime ARN is arn:<partition>:bedrock-agentcore:<region>:<account>:runtime/<agentRuntimeId> and stays the same across versions. Endpoint ARNs append /runtime-endpoint/<name>, including DEFAULT.
  • agentRuntimeName must match [a-zA-Z][a-zA-Z0-9_]{0,47} (no hyphens); invalid names return ValidationException.
  • Each UpdateAgentRuntime increments the version and preserves prior versions for GetAgentRuntime?version= and ListAgentRuntimeVersions. As on AWS, the new version holds exactly the configuration the request carries: an omitted description, authorizerConfiguration, protocolConfiguration or environmentVariables is cleared on it rather than carried over from the previous version.
  • networkConfiguration.networkMode must be PUBLIC or VPC and protocolConfiguration.serverProtocol must be MCP, HTTP, A2A or AGUI; anything else returns the API's ValidationException.
  • Timestamps (createdAt, lastUpdatedAt) are ISO-8601 strings.
  • Config blobs (agentRuntimeArtifact, networkConfiguration, …) are otherwise stored opaquely and echoed back; they are not deeply validated.
  • CreateMemory persists tags, encryptionKeyArn, and memoryExecutionRoleArn; UpdateMemory applies description, eventExpiryDuration, and memoryExecutionRoleArn. As in AWS, memory tags are returned only by ListTagsForResource, never embedded in the memory response shape.

CloudFormation

Floci provisions these resource types:

  • AWS::BedrockAgentCore::Runtime
  • AWS::BedrockAgentCore::RuntimeEndpoint
  • AWS::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