feat: Support mocking Amazon AgentCore API

[kpavlov]

Add support for Amazon AgentCore API using the official AWS SDK for Kotlin.

There is no official OpenAPI specification, bui there are SDKs, e.g. Java:

• https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/bedrockagentcore/package-summary.html
• https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/bedrockagentcorecontrol/package-summary.html

[kpavlov]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Create a new ai-mocks-agentcore module following the established provider module pattern, extending base classes from ai-mocks-core
• Use flexible path matching with predicateMatcher to handle the dynamic {agentRuntimeArn} path segment without requiring changes to mokksy core
• Keep payload models generic (String-based) since AgentCore uses opaque payloads, allowing users to define their own payload structure
• Support both synchronous and SSE streaming responses using the existing streaming infrastructure from mokksy

Design Choices

Design Choice 1: Payload Structure Approach

Options Considered:

1. Define typed model classes for common payload structures (JSON-based)
2. Use generic String/ByteArray payloads with flexible matching, letting users define their own structure

Chosen Option: 2

Rationale: Generic payload approach better matches the API's design where payload format is user-defined, and avoids imposing unnecessary structure on mock consumers.

Design Choice 2: Path Variable and Query Parameter Matching

Options Considered:

1. Extend mokksy core to add query parameter matching infrastructure
2. Use predicateMatcher for path matching and expose convenience methods on the AgentCore request specification

Chosen Option: 2

Rationale: Using predicateMatcher avoids scope creep into mokksy core and follows the pattern used by A2A module for flexible request discrimination.

Design Choice 3: Initial API Scope

Options Considered:

1. Implement both runtime and control plane APIs
2. Focus on runtime InvokeAgentRuntime endpoint only for initial implementation

Chosen Option: 2

Rationale: The runtime invocation endpoint is the primary use case for testing AI agent interactions; control plane APIs can be added in future iterations.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Module Foundation and Build Configuration

Establish the new Gradle module with proper build configuration, dependencies, and the basic mock server class that integrates with the existing framework.

Task 1: Create Gradle Module Structure

Set up the ai-mocks-agentcore module following existing conventions.

• Add ":ai-mocks-agentcore" to the include() block in settings.gradle.kts
• Create ai-mocks-agentcore/build.gradle.kts applying kotlin-convention, dokka-convention, publish-convention, netty-convention, and shadow-convention plugins
• Add dependencies on projects.aiMocksCore (api), Ktor server/client libraries, and kotlinx-serialization
• Add test dependencies on AWS SDK for Kotlin (aws.sdk.kotlin:bedrockagentcore), test-utils, Kotest, and JUnit
• Create source directories: src/commonMain/kotlin/, src/commonTest/kotlin/, src/jvmMain/kotlin/, src/jvmTest/kotlin/

Task 2: Define AgentCore Model Classes

Create Kotlin data classes representing the AgentCore invocation request/response envelope and metadata.

• Create model/ package under ai-mocks-agentcore/src/commonMain/kotlin/dev/mokksy/aimocks/agentcore/
• Define InvokeAgentRuntimeRequest data class with fields: agentRuntimeArn, accountId, qualifier, sessionId, userId, contentType, payload (String)
• Define InvokeAgentRuntimeResponse data class with fields: contentType, sessionId, payload (String)
• Define StreamingChunk data class for SSE streaming responses with data field
• Add @Serializable annotations for JSON serialisation where appropriate
• Keep models minimal since the actual payload structure is user-defined

Task 3: Implement MockAgentCore Server Class

Create the main mock server entry point extending AbstractMockLlm.

• Create MockAgentCore.kt in ai-mocks-agentcore/src/commonMain/kotlin/dev/mokksy/aimocks/agentcore/
• Extend AbstractMockLlm with constructor parameters for port and verbose
• Override baseUrl() to return the appropriate base URL format
• Implement invoke() method that registers a POST route matching /runtimes/{arn}/invocations using predicateMatcher for flexible path matching
• Return an AgentCoreInvokeBuildingStep from the invoke() method
• Add both Kotlin lambda and Java Consumer overloads for the DSL entry point

🤖 Prompt for AI agents

Set up the `ai-mocks-agentcore` Gradle module and implement its foundational
classes, following the conventions of existing provider modules (e.g.,
`ai-mocks-openai`, `ai-mocks-anthropic`).

**Gradle configuration:**
- Add `":ai-mocks-agentcore"` to the `include()` block in `settings.gradle.kts`
- Create `ai-mocks-agentcore/build.gradle.kts` applying plugins:
`kotlin-convention`, `dokka-convention`, `publish-convention`,
`netty-convention`, and `shadow-convention`
- Add `api` dependency on `projects.aiMocksCore`; add Ktor server/client
libraries and kotlinx-serialization as dependencies
- Add test dependencies: `aws.sdk.kotlin:bedrockagentcore`, test-utils, Kotest,
and JUnit
- Create source directories: `src/commonMain/kotlin/`, `src/commonTest/kotlin/`,
`src/jvmMain/kotlin/`, `src/jvmTest/kotlin/`

**Model classes** (in
`ai-mocks-agentcore/src/commonMain/kotlin/dev/mokksy/aimocks/agentcore/model/`):
- `InvokeAgentRuntimeRequest` data class — fields: `agentRuntimeArn`,
`accountId`, `qualifier`, `sessionId`, `userId`, `contentType`, `payload`
(String)
- `InvokeAgentRuntimeResponse` data class — fields: `contentType`, `sessionId`,
`payload` (String)
- `StreamingChunk` data class for SSE streaming responses — field: `data`
- Apply `@Serializable` annotations where appropriate; keep models minimal as
actual payload structure is user-defined

**MockAgentCore server class** (`MockAgentCore.kt` in
`ai-mocks-agentcore/src/commonMain/kotlin/dev/mokksy/aimocks/agentcore/`):
- Extend `AbstractMockLlm` with constructor parameters for `port` and `verbose`
- Override `baseUrl()` to return the appropriate base URL format
- Implement `invoke()` method registering a POST route matching
`/runtimes/{arn}/invocations` using `predicateMatcher` for flexible path
matching
- Return `AgentCoreInvokeBuildingStep` from `invoke()`
- Provide both Kotlin lambda and Java `Consumer` overloads for the DSL entry
point

Phase 2: Request/Response DSL Implementation

Implement the request matching, response building, and streaming capabilities following established patterns from ai-mocks-openai.

Task 1: Create Request Specification

Define the request matching DSL for AgentCore invocations.

• Create AgentCoreInvokeRequestSpecification.kt extending ModelRequestSpecification<InvokeAgentRuntimeRequest>
• Add properties for matching: agentRuntimeArn, accountId, qualifier, sessionId, userId, contentType
• Implement convenience methods: arnContains(String), sessionIdEquals(String), payloadContains(String)
• Store matchers in the inherited requestBody and requestBodyString lists
• Create internal AgentCoreMatchers object with Kotest Matcher implementations for each matching criterion

Task 2: Create Response Specifications

Define response building DSL for both synchronous and streaming responses.

• Create AgentCoreInvokeResponseSpecification.kt extending AbstractResponseSpecification<InvokeAgentRuntimeRequest, InvokeAgentRuntimeResponse>
• Add properties: payload (String), contentType, sessionId, delay
• Create AgentCoreStreamingResponseSpecification.kt extending AbstractStreamingResponseSpecification
• Add properties for streaming: chunks (List), flow (Flow), delayBetweenChunks
• Add JVM-specific extension in jvmMain/ for Java Stream<String> interoperability

Task 3: Create Building Steps

Implement the DSL building steps that connect request matching to response building.

• Create AgentCoreInvokeBuildingStep.kt extending AbstractStreamingBuildingStep<InvokeAgentRuntimeRequest, AgentCoreStreamingResponseSpecification>
• Implement responds(block) for synchronous responses, constructing the response object from specification fields
• Implement respondsStream(block) for SSE streaming, using respondsWithSseStream from mokksy
• Format streaming chunks as SSE-compatible data: lines with proper line endings
• Add both Kotlin suspend lambda and Java Consumer overloads

Task 4: Wire DSL Components in MockAgentCore

Connect all DSL components in the MockAgentCore server class.

• In MockAgentCore.invoke(), construct AgentCoreInvokeRequestSpecification and apply user's configuration block
• Translate specification properties to mokksy matchers using path() with predicateMatcher for ARN matching
• Use containsHeader() for session ID and content type header matching
• Pass configured BuildingStep to AgentCoreInvokeBuildingStep constructor
• Ensure response construction echoes back appropriate fields from request (sessionId, contentType)

🤖 Prompt for AI agents

Implement the full request/response DSL for the `ai-mocks-agentcore` module,
following the patterns established in `ai-mocks-openai`. This phase wires
together request matching, response building, and streaming support.

**Request specification** (`AgentCoreInvokeRequestSpecification.kt`):
- Extend `ModelRequestSpecification<InvokeAgentRuntimeRequest>`
- Add matching properties: `agentRuntimeArn`, `accountId`, `qualifier`,
`sessionId`, `userId`, `contentType`
- Implement convenience methods: `arnContains(String)`,
`sessionIdEquals(String)`, `payloadContains(String)`
- Store matchers in the inherited `requestBody` and `requestBodyString` lists
- Create internal `AgentCoreMatchers` object with Kotest `Matcher`
implementations for each matching criterion

**Response specifications:**
- `AgentCoreInvokeResponseSpecification.kt` — extend
`AbstractResponseSpecification<InvokeAgentRuntimeRequest,
InvokeAgentRuntimeResponse>`; add properties: `payload` (String), `contentType`,
`sessionId`, `delay`
- `AgentCoreStreamingResponseSpecification.kt` — extend
`AbstractStreamingResponseSpecification`; add properties: `chunks`
(List<String>), `flow` (Flow<String>), `delayBetweenChunks`
- Add a JVM-specific extension in `jvmMain/` for Java `Stream<String>`
interoperability

**Building step** (`AgentCoreInvokeBuildingStep.kt`):
- Extend `AbstractStreamingBuildingStep<InvokeAgentRuntimeRequest,
AgentCoreStreamingResponseSpecification>`
- Implement `responds(block)` for synchronous responses, constructing the
response object from specification fields
- Implement `respondsStream(block)` for SSE streaming using
`respondsWithSseStream` from mokksy
- Format streaming chunks as SSE-compatible `data:` lines with proper line
endings
- Provide both Kotlin suspend lambda and Java `Consumer` overloads

**Wiring in MockAgentCore:**
- In `MockAgentCore.invoke()`, construct `AgentCoreInvokeRequestSpecification`
and apply the user's configuration block
- Translate specification properties to mokksy matchers: use `path()` with
`predicateMatcher` for ARN matching; use `containsHeader()` for session ID and
content type header matching
- Pass the configured `BuildingStep` to the `AgentCoreInvokeBuildingStep`
constructor
- Ensure the response construction echoes back appropriate fields from the
request (`sessionId`, `contentType`)

Phase 3: Testing and Integration

Create comprehensive tests validating the mock against the real AWS SDK for Kotlin.

Task 1: Create Unit Tests for Matchers and Models

Add unit tests for the matcher logic and model serialisation.

• Create test class in src/commonTest/kotlin/ for AgentCoreMatchers testing each matcher predicate
• Test model serialisation round-trips using deserializeAndSerialize from test-utils
• Verify matcher positive and negative cases with various input combinations

Task 2: Create Integration Test Base Classes

Set up the test infrastructure following the established two-layer pattern.

• Create AbstractMockAgentCoreTest in src/jvmTest/kotlin/ as the base test class
• Instantiate shared MockAgentCore(verbose = true) as top-level singleton
• Add @BeforeEach for randomised test parameters and @AfterEach calling verifyNoUnmatchedRequests()
• Create AbstractAgentCoreAwsSdkTest extending the base, configuring BedrockAgentCoreClient with endpointUrl pointing to mock's baseUrl()

Task 3: Implement Integration Tests with AWS SDK for Kotlin

Write integration tests exercising the mock with the real AWS SDK client.

• Create InvokeAgentRuntimeTest.kt extending AbstractAgentCoreAwsSdkTest
• Test synchronous invocation: configure mock expectation, call SDK's invokeAgentRuntime(), assert response matches
• Test streaming invocation: configure streaming response with multiple chunks, consume SDK's response stream, verify all chunks received in order
• Test request matching: verify that non-matching requests return 404 and are recorded as unmatched
• Test error responses using respondsError() with appropriate HTTP status codes
• Add tests for header matching (session ID, content type)

Task 4: Add Java Interoperability Test

Verify the DSL works correctly from Java code.

• Create MockAgentCoreJavaTest.java in src/jvmTest/java/
• Use Consumer<> overloads for DSL methods
• Verify the fluent API is ergonomic from Java perspective
• Use AssertJ assertions following the pattern from MockOpenaiJavaTest.java

🤖 Prompt for AI agents

Create comprehensive tests for the `ai-mocks-agentcore` module, validating
matcher logic, model serialisation, and end-to-end integration with the real AWS
SDK for Kotlin.

**Unit tests** (in `src/commonTest/kotlin/`):
- Create a test class for `AgentCoreMatchers`, covering each matcher predicate
with positive and negative cases and various input combinations
- Test model serialisation round-trips using `deserializeAndSerialize` from
test-utils

**Integration test base classes** (in `src/jvmTest/kotlin/`):
- Create `AbstractMockAgentCoreTest` as the base test class; instantiate a
shared `MockAgentCore(verbose = true)` as a top-level singleton
- Add `@BeforeEach` for randomised test parameters and `@AfterEach` calling
`verifyNoUnmatchedRequests()`
- Create `AbstractAgentCoreAwsSdkTest` extending the base, configuring
`BedrockAgentCoreClient` with `endpointUrl` pointing to the mock's `baseUrl()`

**Integration tests** (`InvokeAgentRuntimeTest.kt` extending
`AbstractAgentCoreAwsSdkTest`):
- Test synchronous invocation: configure mock expectation, call SDK's
`invokeAgentRuntime()`, assert response matches
- Test streaming invocation: configure streaming response with multiple chunks,
consume SDK's response stream, verify all chunks received in order
- Test request matching: verify non-matching requests return 404 and are
recorded as unmatched
- Test error responses using `respondsError()` with appropriate HTTP status
codes
- Add tests for header matching (session ID, content type)

**Java interoperability test** (`MockAgentCoreJavaTest.java` in
`src/jvmTest/java/`):
- Use `Consumer<>` overloads for all DSL methods
- Verify the fluent API is ergonomic from a Java perspective
- Use AssertJ assertions, following the pattern from `MockOpenaiJavaTest.java`

Research

The ai-mocks project is a Kotlin Multiplatform library providing mock servers for various AI provider APIs. It follows a layered architecture: mokksy (core HTTP mock server with Ktor), ai-mocks-core (shared AI mock abstractions), and provider-specific modules (ai-mocks-openai, ai-mocks-anthropic, etc.). Each provider module extends AbstractMockLlm, implements request/response specifications, and provides a fluent DSL for test setup. The build system uses convention plugins for consistent configuration across modules.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the `ai-mocks-agentcore` Gradle module and implement its foundational
classes, following the conventions of existing provider modules (e.g.,
`ai-mocks-openai`, `ai-mocks-anthropic`).

**Gradle configuration:**
- Add `":ai-mocks-agentcore"` to the `include()` block in `settings.gradle.kts`
- Create `ai-mocks-agentcore/build.gradle.kts` applying plugins:
`kotlin-convention`, `dokka-convention`, `publish-convention`,
`netty-convention`, and `shadow-convention`
- Add `api` dependency on `projects.aiMocksCore`; add Ktor server/client
libraries and kotlinx-serialization as dependencies
- Add test dependencies: `aws.sdk.kotlin:bedrockagentcore`, test-utils, Kotest,
and JUnit
- Create source directories: `src/commonMain/kotlin/`, `src/commonTest/kotlin/`,
`src/jvmMain/kotlin/`, `src/jvmTest/kotlin/`

**Model classes** (in
`ai-mocks-agentcore/src/commonMain/kotlin/dev/mokksy/aimocks/agentcore/model/`):
- `InvokeAgentRuntimeRequest` data class — fields: `agentRuntimeArn`,
`accountId`, `qualifier`, `sessionId`, `userId`, `contentType`, `payload`
(String)
- `InvokeAgentRuntimeResponse` data class — fields: `contentType`, `sessionId`,
`payload` (String)
- `StreamingChunk` data class for SSE streaming responses — field: `data`
- Apply `@Serializable` annotations where appropriate; keep models minimal as
actual payload structure is user-defined

**MockAgentCore server class** (`MockAgentCore.kt` in
`ai-mocks-agentcore/src/commonMain/kotlin/dev/mokksy/aimocks/agentcore/`):
- Extend `AbstractMockLlm` with constructor parameters for `port` and `verbose`
- Override `baseUrl()` to return the appropriate base URL format
- Implement `invoke()` method registering a POST route matching
`/runtimes/{arn}/invocations` using `predicateMatcher` for flexible path
matching
- Return `AgentCoreInvokeBuildingStep` from `invoke()`
- Provide both Kotlin lambda and Java `Consumer` overloads for the DSL entry
point
===============================================================================

Task: 2

Implement the full request/response DSL for the `ai-mocks-agentcore` module,
following the patterns established in `ai-mocks-openai`. This phase wires
together request matching, response building, and streaming support.

**Request specification** (`AgentCoreInvokeRequestSpecification.kt`):
- Extend `ModelRequestSpecification<InvokeAgentRuntimeRequest>`
- Add matching properties: `agentRuntimeArn`, `accountId`, `qualifier`,
`sessionId`, `userId`, `contentType`
- Implement convenience methods: `arnContains(String)`,
`sessionIdEquals(String)`, `payloadContains(String)`
- Store matchers in the inherited `requestBody` and `requestBodyString` lists
- Create internal `AgentCoreMatchers` object with Kotest `Matcher`
implementations for each matching criterion

**Response specifications:**
- `AgentCoreInvokeResponseSpecification.kt` — extend
`AbstractResponseSpecification<InvokeAgentRuntimeRequest,
InvokeAgentRuntimeResponse>`; add properties: `payload` (String), `contentType`,
`sessionId`, `delay`
- `AgentCoreStreamingResponseSpecification.kt` — extend
`AbstractStreamingResponseSpecification`; add properties: `chunks`
(List<String>), `flow` (Flow<String>), `delayBetweenChunks`
- Add a JVM-specific extension in `jvmMain/` for Java `Stream<String>`
interoperability

**Building step** (`AgentCoreInvokeBuildingStep.kt`):
- Extend `AbstractStreamingBuildingStep<InvokeAgentRuntimeRequest,
AgentCoreStreamingResponseSpecification>`
- Implement `responds(block)` for synchronous responses, constructing the
response object from specification fields
- Implement `respondsStream(block)` for SSE streaming using
`respondsWithSseStream` from mokksy
- Format streaming chunks as SSE-compatible `data:` lines with proper line
endings
- Provide both Kotlin suspend lambda and Java `Consumer` overloads

**Wiring in MockAgentCore:**
- In `MockAgentCore.invoke()`, construct `AgentCoreInvokeRequestSpecification`
and apply the user's configuration block
- Translate specification properties to mokksy matchers: use `path()` with
`predicateMatcher` for ARN matching; use `containsHeader()` for session ID and
content type header matching
- Pass the configured `BuildingStep` to the `AgentCoreInvokeBuildingStep`
constructor
- Ensure the response construction echoes back appropriate fields from the
request (`sessionId`, `contentType`)
===============================================================================

Task: 3

Create comprehensive tests for the `ai-mocks-agentcore` module, validating
matcher logic, model serialisation, and end-to-end integration with the real AWS
SDK for Kotlin.

**Unit tests** (in `src/commonTest/kotlin/`):
- Create a test class for `AgentCoreMatchers`, covering each matcher predicate
with positive and negative cases and various input combinations
- Test model serialisation round-trips using `deserializeAndSerialize` from
test-utils

**Integration test base classes** (in `src/jvmTest/kotlin/`):
- Create `AbstractMockAgentCoreTest` as the base test class; instantiate a
shared `MockAgentCore(verbose = true)` as a top-level singleton
- Add `@BeforeEach` for randomised test parameters and `@AfterEach` calling
`verifyNoUnmatchedRequests()`
- Create `AbstractAgentCoreAwsSdkTest` extending the base, configuring
`BedrockAgentCoreClient` with `endpointUrl` pointing to the mock's `baseUrl()`

**Integration tests** (`InvokeAgentRuntimeTest.kt` extending
`AbstractAgentCoreAwsSdkTest`):
- Test synchronous invocation: configure mock expectation, call SDK's
`invokeAgentRuntime()`, assert response matches
- Test streaming invocation: configure streaming response with multiple chunks,
consume SDK's response stream, verify all chunks received in order
- Test request matching: verify non-matching requests return 404 and are
recorded as unmatched
- Test error responses using `respondsError()` with appropriate HTTP status
codes
- Add tests for header matching (session ID, content type)

**Java interoperability test** (`MockAgentCoreJavaTest.java` in
`src/jvmTest/java/`):
- Use `Consumer<>` overloads for all DSL methods
- Verify the fluent API is ergonomic from a Java perspective
- Use AssertJ assertions, following the pattern from `MockOpenaiJavaTest.java`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!