gaelic-ghost/socket/build-jvm-agent-service

Build JVM Agent Service

Use this skill after choose-service-shape identifies a JVM service and the application needs Google Agent Development Kit (ADK), not merely one model API call. Keep Java/Kotlin domain behavior independent from ADK orchestration at the application edge.

Source Check

• Google ADK: <https://adk.dev/>
• ADK Java API: <https://google.github.io/adk-docs/api-reference/java/>
• Java: <https://docs.oracle.com/en/java/>
• Kotlin: <https://kotlinlang.org/docs/home.html>

Confirm the exact ADK language/runtime and model adapter before changing code. ADK documents local-model adapters, but an Ollama-compatible endpoint must still pass the exact model capability gate below.

Workflow

1. Keep the existing Java/Kotlin language decision and build tool; do not add a

second JVM language merely for an agent library.

1. Define the non-agent baseline, typed request/result, model endpoint/exact

model, allowed tools, and no-op behavior.

1. Use one ADK agent with narrow read-only function or MCP tools. The executor

validates authorization, schema, timeout, and result shape independently of model output.

1. Prove the exact server/model combination can make valid tool calls, return

schema-conforming structured output, decline unnecessary calls, recover from malformed calls, and stop at a maximum-step boundary.

1. Add sessions, memory, graph workflows, A2A, or persistence only when the

product visibly needs resume, routing, or cross-agent behavior. Document retention, restart recovery, and migrations.

1. Test fake tools first, then model-adapter integration in a read-only or

disposable environment. Report attempted and executed side effects apart.

1. Promote external writes only through auto-with-escalation with the exact

target, action, evidence, and approval point named.

Validation

Use the existing build owner: ./gradlew test, mvn test, or sbt test. Include unit tests for domain/tool authorization, agent workflow tests with fake tools, and an opt-in local-model capability smoke test. Do not make a downloaded model or live endpoint a normal unit-test prerequisite.

Guardrails

• Do not make Gemini or Google Cloud a required dependency of a local-first

service unless the product explicitly chooses it.

• Do not expose an agent API publicly or start a background runtime by default.
• Do not trust an agent instruction as an authorization boundary.
• Do not add A2A, MCP, graphs, or multi-agent delegation without a concrete

caller and a testable state/recovery need.