Embabel agents that are checked before they run

An Agent Skill for scaffolding, testing and plan-checking Embabel agents on the JVM: Java or Kotlin, Spring Boot, Maven or Gradle. Works with Claude Code, Cursor, Copilot, Codex and other agents that load skills.

CI License: Apache 2.0 Embabel version Spring Boot version
Get started View on GitHub

Quick start

Install the skill:

npx skills add hadirsa/embabeler

Then ask your agent for what you want, for example "Create an Embabel agent that triages support tickets, with tests."

Or install by hand for Claude Code:

git clone https://github.com/hadirsa/embabeler ~/.claude/skills/embabeler

Or generate a project directly, from the skill's directory:

node scripts/create-project.mjs trip-planner com.acme.trip --output-dir "$PWD/.."
cd ../trip-planner && ./mvnw test

To see the output without installing anything, browse embabeler-sample-agent-demo, a project generated with Embabeler 0.1.0 (Java, Maven, Embabel 1.5.2). It is a snapshot; generate your own for the current versions.

Requirements

Features

Verified scaffold

Generates a runnable project with an agent, domain types, a tool, and unit and integration tests that need no LLM and no API key.

Plan check

AgentPlanTest fails the build when an agent can never reach its goal, which the compiler cannot catch.

Tested references

Every Java snippet in the docs is compiled and tested here, or marked as copied from an official source and checked against it.

Cookbook and pitfalls

Tested examples of routing, conditions, states, domain tools, review loops and human-in-the-loop, plus deliberately broken agents.

Kept current

CI builds the scaffold in five variants on every push, and a weekly job rebuilds it against the newest Embabel release.

Plan check

Embabel plans from method signatures: an @Action's parameter types are its preconditions, its return type is its effect, and the planner chains actions to the @AchievesGoal. Many mistakes compile and then stall at runtime.

AgentPlanTest reads the agent model Embabel builds at startup, so it works for Java and Kotlin. It fails the build on a missing or unreachable goal, a dependency cycle, or a condition used in pre that no action declares in post. It warns about ambiguous producers and weak flow types.

Example, from the deliberately broken cycle agent in the cookbook (output of the static checker):

ERROR   UNREACHABLE_GOAL  CyclePitfallAgent.java:38
         Goal action write() can never run: Outline, Research is produced
         only by actions that cannot run themselves (a dependency cycle
         or missing link).
WARNING UNREACHABLE_ACTION  CyclePitfallAgent.java:27
         Action outline() can never run: waiting for Research.
WARNING UNREACHABLE_ACTION  CyclePitfallAgent.java:32
         Action research() can never run: waiting for Outline.

1 agent(s) checked: 1 error(s), 2 warning(s).

Add the test to an existing project (Java or Kotlin):

node scripts/add-plan-check.mjs /path/to/project com.acme.yourpackage

Run the static checker without a build. It reads Java sources only, defaults to src/main/java, and exits 1 on errors (--strict also fails on warnings, --json prints JSON):

node scripts/check-plan.mjs path/to/src/main/java

Scaffold

scripts/create-project.mjs <name> <package> generates a project on the tested version combination.

OptionEffect
--kotlinKotlin sources instead of Java
--gradleGradle build instead of Maven
--with-cookbookAdds the tested pattern examples (Java only; not combinable with --kotlin)
--java-version 21Targets Java 21
--agent-name, --output-dir, --latest, --dry-runSee the usage line of the script

Example prompts

Learn more