Goes beyond a finite state machine or sequential execution with nesting by introducing a true planning step, using a non-LLM AI algorithm. This enables the system to perform tasks it wasn’t programmed to do by combining known steps in a novel order, as well as make decisions about parallelization and other runtime behavior.

Because of dynamic planning, adding more domain objects, actions, goals and conditions can extend the capability of the system, without editing FSM definitions or existing code.

Actions, goals and conditions are informed by a domain model, which can include behavior. Everything is strongly typed and prompts and manually authored code interact cleanly. No more magic maps. Enjoy full refactoring support.

Clean separation between programming model and platform internals allows running locally while potentially offering higher QoS in production without changing application code.

It is easy to build applications that mix LLMs, ensuring the most cost-effective yet capable solution. This enables the system to leverage the strengths of different models for different tasks. In particular, it facilitates the use of local models for point tasks. This can be important for cost and privacy.

Built on Spring and the JVM, making it easy to access existing enterprise functionality and capabilities. For example:

Both unit testing and agent end-to-end testing are easy from the ground up.

Let’s look at a complete example that demonstrates how Embabel infers conditions from input/output types and manages data flow between actions. This example comes from the Embabel Agent Examples repository:

State is managed by the framework, through the process blackboard.

Based on the type signatures alone, Embabel automatically infers this execution plan for the example agent above:

Goal: Produce a Writeup (final return type of @AchievesGoal action)

The initial plan:

Execution sequence:

UserInput → extractStarPerson() → StarPerson → retrieveHoroscope() → Horoscope → findNewsStories() → RelevantNewsStories → writeup() → Writeup and achieves goal.

Automatic Orchestration: No manual workflow definition needed - the agent figures out the sequence from type dependencies. This is particularly beneficial if things go wrong, as the planner can re-evaluate the situation and may be able to find an alternative path to the goal.

Dynamic Replanning: After each action, the agent reassesses what’s possible based on available data objects.

Type Safety: Compile-time guarantees that data flows correctly between actions. No magic string keys.

Flexible Execution: If multiple actions could produce the required input type, the agent chooses based on context and efficiency. (Actions can have cost and value.)

This demonstrates how Embabel transforms simple method signatures into sophisticated multi-step agent behavior, with the complex orchestration handled automatically by the framework.

Add the appropriate Embabel Agent Spring Boot starter to your build file depending on your choice of application type:

Before running your application, you’ll need to set up your environment with API keys for the LLM providers you plan to use.

Example .env file:

The quickest way to get started with Embabel is to run the examples:

Set your API keys:

Spring Shell is an easy way to interact with the Embabel agent framework, especially during development.

Type help to see available commands. Use execute or x to run an agent:

This will look for an agent, choose the star finder agent and run the flow. -p will log prompts -r will log LLM responses. Omit these for less verbose logging.

Options:

Use the chat command to enter an interactive chat with the agent. It will attempt to run the most appropriate agent for each command.

Try these commands in the shell:

Particularly during development, you may want to implement your own shell commands to try agents or flows. Simply write a Spring Shell component and Spring will inject it and register it automatically.

For example, you can inject the AgentPlatform and use it to invoke agents directly, as in this code from the examples repository:

Create a new project from the Java template or Kotlin template by clicking "Use this template" on GitHub.

Or use the project creator:

The Java template includes a WriteAndReviewAgent that demonstrates key concepts:

Multiple LLMs with Different Configurations:

Actions and Goals:

Domain Objects:

Set your API keys and run the shell:

In the shell, try:

The agent will:

An AgentProcess maintains state throughout its execution and can transition between various states:

Process States:

Process Execution Methods:

These methods are not directly called by user code, but are managed by the framework to control execution flow.

Each AgentProcess maintains:

Planning occurs after each action execution using Goal-Oriented Action Planning (GOAP). The planning process:

This creates a dynamic OODA loop (Observe-Orient-Decide-Act): - Observe: Check current blackboard state and action results - Orient: Understand what has changed since the last planning cycle - Decide: Formulate or update the plan based on new information - Act: Execute the next planned action

The replanning approach allows agents to:

The Blackboard serves as the shared memory system that maintains state throughout the agent process execution. It implements the Blackboard architectural pattern, a knowledge-based system approach.

Most of the time, user code doesn’t need to interact with the blackboard directly, as it is managed by the framework. For example, action inputs come from the blackboard, and action outputs are automatically added to the blackboard, and conditions are evaluated based on its contents.

Key Characteristics:

Core Operations:

Data Flow:

The blackboard enables:

By default, items in the blackboard are matched by type. When there are multiple candidates of the same type, the most recently added one is provided. It is also possible to assign a specific name to blackboard items.

An example of explicit binding in an action method:

The following example requires a Thing named thingOne to be present in the blackboard:

The following example uses @Action.outputBinding to cause a thingOne to be bound in the blackboard, satisfying the previous example:

Embabel offers a way to store longer term state: the com.embabel.agent.core.Context. While a blackboard is tied to a specific agent process, a context can persist across multiple processes.

Contexts are identified by a unique contextId string. When starting an agent process, you can specify a contextId in the ProcessOptions. This will populate that process’s blackboard with any data stored in the specified context.

Unlike simple structs or DTOs, Embabel domain objects can encapsulate business logic and expose it to LLMs through the @Tool annotation. For example:

The @Tool annotation allows you to selectively expose domain object methods to LLMs. For example:

Domain objects can be used naturally in action methods, combining LLM interactions with traditional object-oriented programming. The availability of the domain object instances also drives Embabel planning.

As outlined in Rod Johnson’s blog introducing DICE (Domain-Integrated Context Engineering) in Context Engineering Needs Domain Understanding, domain understanding is fundamental to effective context engineering. Domain objects serve as the bridge between:

This approach ensures that agents work with meaningful business entities rather than generic data structures, leading to more natural and effective AI interactions.

Annotate your Spring Boot application class to get agentic behavior.

Example:

This is a normal Spring Boot application class. You can add other Spring Boot annotations as needed. Add the following dependency to your pom.xml to include the Ollama model provider starter:

Other providers such as OpenAI, Anthropic, AWS Bedrock, Docker Models, etc. can be added similarly by including their respective starter dependencies.

The following table lists all available configuration properties in Embabel Agent Platform. Properties are organized by their configuration prefix and include default values where applicable. They can be set via application.properties, application.yml, profile-specific configuration files or environment variables, as per standard Spring configuration practices.

This annotation is used on a class to define an agent. It is a Spring stereotype annotation, so it triggers Spring component scanning. Your agent class will automatically be registered as a Spring bean. It will also be registered with the agent framework, so it can be used in agent processes.

You must provide the description parameter, which is a human-readable description of the agent. This is particularly important as it may be used by the LLM in agent selection.

The @Action annotation is used to mark methods that perform actions within an agent.

Action metadata can be specified on the annotation, including:

The @Condition annotation is used to mark methods that evaluate conditions. They can take an OperationContext parameter to access the blackboard and other infrastructure. If they take domain object parameters, the condition will automatically be false until suitable instances are available.

@Action methods must have at least one parameter. @Condition methods must have zero or more parameters, but otherwise follow the same rules as @Action methods regarding parameters. Ordering of parameters is not important.

Parameters fall in two categories:

The ActionContext or ExecutingOperationContext subtype can be used in action methods. It adds asSubProcess methods that can be used to run other agents in subprocesses. This is an important element of composition.

The @RequireNameMatch annotation can be used to bind parameters by name.

The trigger field on the @Action annotation enables reactive behavior where an action only fires when a specific type is the most recently added value to the blackboard. This is useful in event-driven scenarios where you want to react to a particular event even when multiple parameters of various types are available.

For example, in a chat system you might want an action to fire only when a new user message arrives, not when other context is updated:

Without trigger, an action fires as soon as all its parameters are available on the blackboard. With trigger, the specified type must additionally be the most recent value added.

This is particularly useful when:

Action methods normally return a single domain object.

Nullable return types are allowed. Returning null will trigger replanning. There may or not be an alternative path from that point, but it won’t be what the planner was previously trying to achieve.

There is a special case where the return type can essentially be a union type, where the action method can return one ore more of several types. This is achieved by a return type implementing the SomeOf tag interface. Implementations of this interface can have multiple nullable fields. Any non-null values will be bound to the blackboard, and the postconditions of the action will include all possible fields of the return type.

For example:

This enables routing scenarios in an elegant manner.

Routing can also be achieved via subtypes, as in the following example:

Embabel makes it easy to seamlessly integrate LLM invocation and application code, using common types. An @Action method is a normal method, and can use any libraries or frameworks you like.

The only special thing about it is its ability to use the OperationContext parameter to access the blackboard and invoke LLMs.

The @AchievesGoal annotation can be added to an @Action method to indicate that the completion of the action achieves a specific goal.

If an annotated agent class implements the StuckHandler interface, it can handle situations where an action is stuck itself. For example, it can add data to the blackboard.

Example:

An @Action method can invoke another agent process. This is often done to use a stereotyped process that is composed using the DSL.

Use the ActionContext.asSubProcess method to create a sub-process from the action context.

For example:

The RunSubagent utility provides a convenient way to run a nested agent from within an @Action method without needing direct access to ActionContext. This is particularly useful when you want to delegate work to another @Agent-annotated class or an Agent instance.

There are a number of standard workflows, constructed by builders, that meet common requirements. These can be used to create agents that will be exposed as Spring beans, or within @Action methods within other agents. All are type safe. As far as possible, they use consistent APIs.

Creating a simple agent:

A more complex example:

Whereas the @Agent annotation causes a class to be picked up immediately by Spring, with the DSL you’ll need an extra step to register an agent with Spring. As shown in the example below, any @Bean of Agent type results auto registration, just like declaring a class annotated with @Agent does.

The LlmOptions class specifies which LLM to use and its hyperparameters. It’s defined in the embabel-common project and provides a fluent API for LLM configuration:

Important Methods:

LlmOptions is serializable to JSON, so you can set properties of type LlmOptions in application.yml and other application configuration files. This is a powerful way of externalizing not only models, but hyperparameters.

All LLM calls in user applications should be made via the PromptRunner interface. Once created, a PromptRunner can run multiple prompts with the same LLM, hyperparameters, tool groups and PromptContributors.

Represents an image for use with vision-capable LLMs.

Factory Methods:

For uncommon image formats or if auto-detection fails, use AgentImage.create() with an explicit MIME type.

Implement one or more methods annotated with @Tool on a class. You do not need to annotate the class itself. Each annotated method represents a distinct tool that will be exposed to the LLM.

A simple example of a tool method:

Classes implementing tools can be stateful. They are often domain objects. Tools on mapped entities are especially useful, as they can encapsulate state that is never exposed to the LLM. See Domain Tools: Direct Access, Zero Ceremony for a discussion of tool use patterns.

The @Tool annotation comes from Spring AI.

Tool methods can have any visibility, and can be static or instance scope. They are allowed on inner classes.

You can obtain the current AgentProcess in a Tool method implementation via AgentProcess.get(). This enables tools to bind to the AgentProcess, making objects available to other actions. For example:

Embabel introduces the concept of a tool group. This is a level of indirection between user intent and tool selection. For example, we don’t ask for Brave or Google web search: we ask for "web" tools, which may be resolved differently in different environments.

Tool groups are often backed by MCP.

In addition to Spring AI’s @Tool annotation, Embabel provides its own framework-agnostic Tool interface in the com.embabel.agent.api.tool package. This allows you to create tools that are not tied to any specific LLM framework, making your code more portable and testable.

The Tool interface includes nested types to avoid naming conflicts with framework-specific types: