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
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
- Keep the existing Java/Kotlin language decision and build tool; do not add a
second JVM language merely for an agent library.
- Define the non-agent baseline, typed request/result, model endpoint/exact
model, allowed tools, and no-op behavior.
- 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.
- 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.
- 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.
- Test fake tools first, then model-adapter integration in a read-only or
disposable environment. Report attempted and executed side effects apart.
- 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.
1---2name: build-jvm-agent-service3description: Build a local-first Java or Kotlin Google ADK agent service with explicit tools, model capability checks, evaluation fixtures, and draft-before-write promotion.4license: Apache-2.05---67# Build JVM Agent Service89Use this skill after `choose-service-shape` identifies a JVM service and the10application needs Google Agent Development Kit (ADK), not merely one model API11call. Keep Java/Kotlin domain behavior independent from ADK orchestration at12the application edge.1314## Source Check1516- Google ADK: <https://adk.dev/>17- ADK Java API: <https://google.github.io/adk-docs/api-reference/java/>18- Java: <https://docs.oracle.com/en/java/>19- Kotlin: <https://kotlinlang.org/docs/home.html>2021Confirm the exact ADK language/runtime and model adapter before changing code.22ADK documents local-model adapters, but an Ollama-compatible endpoint must23still pass the exact model capability gate below.2425## Workflow26271. Keep the existing Java/Kotlin language decision and build tool; do not add a28 second JVM language merely for an agent library.292. Define the non-agent baseline, typed request/result, model endpoint/exact30 model, allowed tools, and no-op behavior.313. Use one ADK agent with narrow read-only function or MCP tools. The executor32 validates authorization, schema, timeout, and result shape independently of33 model output.344. Prove the exact server/model combination can make valid tool calls, return35 schema-conforming structured output, decline unnecessary calls, recover from36 malformed calls, and stop at a maximum-step boundary.375. Add sessions, memory, graph workflows, A2A, or persistence only when the38 product visibly needs resume, routing, or cross-agent behavior. Document39 retention, restart recovery, and migrations.406. Test fake tools first, then model-adapter integration in a read-only or41 disposable environment. Report attempted and executed side effects apart.427. Promote external writes only through `auto-with-escalation` with the exact43 target, action, evidence, and approval point named.4445## Validation4647Use the existing build owner: `./gradlew test`, `mvn test`, or `sbt test`.48Include unit tests for domain/tool authorization, agent workflow tests with49fake tools, and an opt-in local-model capability smoke test. Do not make a50downloaded model or live endpoint a normal unit-test prerequisite.5152## Guardrails5354- Do not make Gemini or Google Cloud a required dependency of a local-first55 service unless the product explicitly chooses it.56- Do not expose an agent API publicly or start a background runtime by default.57- Do not trust an agent instruction as an authorization boundary.58- Do not add A2A, MCP, graphs, or multi-agent delegation without a concrete59 caller and a testable state/recovery need.
gaelic-ghost