Overview

This section explains how to create and install your own handlers. For the available server/proxy interaction paths and how host code calls an agent, start with Interacting through agents.

Agent operations let your library execute code inside an existing Anvil platform agent. The host sends a typed request; a handler in the server or proxy returns a typed response. Use this boundary for native observations or actions that the player protocol does not provide.

Test → running process → Echo capability → RequestChannel
                                           │ launcher binding
                                           ▼
                                       AgentClient
                                           │ request
                                           ▼
                              platform agent → Echo handler

The shared operation contract belongs on both sides. Platform SDK code belongs only in the handler artifact. The public capability API stays separate and depends only on anvil-api. The process owns the capability; an agent operation supplies its native handler mechanism.

For registration and native-service method contracts, read the AgentOperationProvider, AgentOperationRegistry, and PlatformAgent source Javadocs. These links use dev; select your release tag when checking a released version.

1. Define the operation and handler.
2. Install the handler JAR into the managed workspace.
3. Call it from an agent-backed process capability.

The Echo example demonstrates installation and request dispatch. For a useful test observation, return application state from the native platform service and assert that state in the journey.