https://github.com/embabel/java-agent-template
Java agent template
https://github.com/embabel/java-agent-template
Last synced: 5 months ago
JSON representation
Java agent template
- Host: GitHub
- URL: https://github.com/embabel/java-agent-template
- Owner: embabel
- License: apache-2.0
- Created: 2025-06-09T07:13:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-24T06:16:19.000Z (6 months ago)
- Last Synced: 2025-12-25T01:04:15.079Z (6 months ago)
- Language: Java
- Homepage:
- Size: 241 KB
- Stars: 109
- Watchers: 7
- Forks: 36
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-embabel - Java agent template
README
# Generated Agent Project
   
Starting point for your own agent development using the [Embabel framework](https://github.com/embabel/embabel-agent).
Uses Spring Boot 3.5.9 and Embabel 0.3.1.
Add your magic here!
Illustrates:
- An injected demo showing how any Spring component can be injected with an Embabel `Ai` instance to enable it to
perform LLM operations.
- A simple agent
- Unit tests for an agent verifying prompts and hyperparameters
> For the Kotlin equivalent, see
> our [Kotlin agent template](https://github.com/embabel/kotlin-agent-template).
# Running
Run the shell script to start Embabel under Spring Shell:
```bash
./scripts/shell.sh
```
There is a single example
agent, [WriteAndReviewAgent](./src/main/java/com/embabel/template/agent/WriteAndReviewAgent.java).
It uses one LLM with a high temperature and creative persona to write a story based on your input,
then another LLM with a low temperature and different persona to review the story.
When the Embabel shell comes up, invoke the story agent like this:
```
x "Tell me a story about...[your topic]"
```
Try the following other shell commands:
- `demo`: Runs the same agent, invoked programmatically, instead of dynamically based on user input.
See [DemoCommands.java](./src/main/java/com/embabel/template/DemoShell.java) for the
implementation.
- `animal`: Runs a simple demo using an Embabel injected `Ai` instance to call an LLM.
See [InjectedDemo](./src/main/java/com/embabel/template/injected/InjectedDemo.java).
## Suggested Next Steps
To get a feel for working with Embabel, try the following:
- Modify the prompts in `WriteAndReviewAgent` and `InjectedDemo`.
- Experiment with different models and hyperparameters by modifying `withLlm` calls.
- Integrate your own services, injecting them with Spring. All Embabel `@Agent` classes are Spring beans.
- Run the tests with `mvn test` and modify them to experiment with prompt verification.
To see tool support, check out the more
complex [Embabel Agent API Examples](https://github.com/embabel/embabel-agent-examples) repository.
## Model support
Embabel integrates with any LLM supported by Spring AI.
See [LLM integration guide](docs/llm-docs.md) (work in progress).
Also see [Spring AI models](https://docs.spring.io/spring-ai/reference/api/index.html).
## Testing
This repository includes unit tests and integration tests demonstrating how to test Embabel agents.
### Running Tests
```bash
mvn test
```
### Unit Tests
Unit tests use Embabel's `FakeOperationContext` and `FakePromptRunner` to test agent actions in isolation without
calling actual LLMs.
See [WriteAndReviewAgentTest.java](./src/test/java/com/embabel/template/agent/WriteAndReviewAgentTest.java) for examples
of:
- Creating a fake context with `FakeOperationContext.create()`
- Setting up expected responses with `context.expectResponse()`
- Verifying prompt content contains expected values
- Inspecting LLM invocations via `promptRunner.getLlmInvocations()`
```java
var context = FakeOperationContext.create();
context.expectResponse(new Story("Once upon a time..."));
var story = agent.craftStory(userInput, context.ai());
var prompt = context.getLlmInvocations().getFirst().getMessages().getFirst().getContent();
assertTrue(prompt.contains("knight"));
```
### Integration Tests
Integration tests extend `EmbabelMockitoIntegrationTest` to test complete agent workflows under Spring Boot with a fully
configured `AgentPlatform`.
See [WriteAndReviewAgentIntegrationTest.java](./src/test/java/com/embabel/template/agent/WriteAndReviewAgentIntegrationTest.java)
for examples of:
- Mocking LLM responses with `whenCreateObject()` and `whenGenerateText()`
- Running complete agent workflows via `AgentInvocation`
- Verifying LLM calls and hyperparameters with `verifyCreateObjectMatching()` and `verifyGenerateTextMatching()`
```java
whenCreateObject(prompt -> prompt.contains("Craft a short story"), Story.class)
.thenReturn(new Story("AI will transform our world..."));
var invocation = AgentInvocation.create(agentPlatform, ReviewedStory.class);
var result = invocation.invoke(input);
verifyCreateObjectMatching(
prompt -> prompt.contains("Craft a short story"),
Story.class,
llm -> llm.getLlm().getTemperature() == 0.7
);
```
## Contributors
[](https://github.com/embabel/java-agent-template/graphs/contributors)