DOCSEARCHbyAlgolia
Submit Docs

Embabel Agent Framework

repository·main·Indexed 25 days ago

https://github.com/embabel/embabel-agent

A JVM framework for building agentic flows that combine LLM interactions with strongly-typed domain models and code. It features dynamic planning via A* GOAP and Utility AI, integrates with the Spring ecosystem and Spring AI, and supports Human in the Loop (HITL) workflows using Awaitable objects. The framework provides a Kotlin DSL and annotation-based API for defining agents, along with structured prompt support (Persona, CoStar) and a segregated configuration model for platform and application properties.

Tokens
98.1K
Snippets
253
Records
436
Agent score
87%

What's inside embabel-agent

  1. Overview of Embabel Agent Observability Features

    main

    Embabel Agent Observability provides deep visibility into the agent lifecycle and GenAI interactions. Key features include:

    • Agent Lifecycle & Hierarchy: Traces agent creation, execution, and sub-agent parent-child relationships.
    • GenAI Specific Tracing: Detailed spans for embabel.llm (including token usage and cost), embabel.embedding, embabel.tool (richer than Spring AI's native tool spans), and embabel.rag (including RAGAS quality metrics).
    • Tool & Loop Tracing: Monitors the embabel.tool_loop and individual tool executions.
    • Planning & State: Tracks embabel.goal, embabel.replan, and workflow state transitions (e.g., WAITING, PAUSED, STUCK).
    • Metrics: Automatic Micrometer counters/gauges for active agents, LLM tokens, cost, and errors.
    • Semantic Conventions: Uses OpenTelemetry GenAI semantic conventions (gen_ai.*) for consistency.
    • Developer Tools: Includes a @Tracked annotation for custom operation tracking and automatic SLF4J MDC log correlation.

  2. Overview of Embabel Agent Shell Module

    main

    The Embabel Agent Shell Module is an interactive Spring Shell experience for the Embabel Agent platform. It provides a terminal-based interface for agent management, chat sessions, task execution, and system operations. It includes features like:

    • Chat Session Management: Interactive agent chats.
    • Form Handling: Terminal-based inputs (TextField, Button).
    • Human-in-the-loop: Goal approval via GoalChoiceApprover.
    • Markdown Support: ANSI-styled console output for headers, code blocks, and links.
    • Output Formatting: Formatted process output including usage and cost information.

  4. Apply Domain Integrated Context Engineering (DICE)

    main

    Domain Integrated Context Engineering (DICE) is a method used to enhance context engineering by grounding both LLM inputs and outputs in typed domain objects.

    Instead of using untyped prompts, DICE uses business-aware models to provide:

    • Precision: Structured context instead of raw text.
    • Testability: Reliable, inspectable, and manipulable context artifacts.
    • Integration: Seamless connection with existing typed systems.

  5. Understand the value proposition of Embabel Agent Framework

    main

    Embabel is a high-level agent framework designed for the JVM that builds upon Spring AI. It provides abstractions to make agentic systems more manageable, testable, and robust compared to direct LLM invocation or lower-level APIs like Spring AI.

    Key benefits include:

    • Simplified LLM Interactions: Breaks down complex tasks into focused, reusable, and cost-effective sub-interactions.
    • Testability: Facilitates both unit and integration testing for agentic workflows.
    • Composability: Allows subflows and individual actions to be reused across different parts of an application.
    • Robustness: Enables workflow managers to control execution, handle retries, and maintain state.
    • Safety: Provides multiple points to apply guardrails.
    • JVM Integration: Leverages existing JVM-based business logic and infrastructure assets.

    Relationship with Spring AI: While Embabel embraces the Spring component model and builds on Spring AI, it operates at a higher level of abstraction. If Spring AI is analogous to the Servlet API, Embabel is analogous to Spring MVC.

  6. Use Tools to extend LLM capabilities

    main

    Tools allow an LLM to interact with the outside world, bridging the gap between text prediction and real-world action.

    When tools are provided to an agent, the LLM can:

    • Reason and Act: Interpret requests, plan steps, and delegate tasks to tools in a loop (inspired by the ReAct pattern).
    • Perform Side Effects: Execute tasks like creating database records, generating visualizations, or invoking external processes.
    • Access Domain Data: In Embabel, many tools are bound to domain objects to provide accurate, non-hallucinated information.

  7. Understand the A* GOAP Planner Algorithm

    main

    The A* GOAP (Goal-Oriented Action Planning) Planner is used to find optimal sequences of actions to achieve specific goals. It uses an A* search algorithm to navigate from an initial world state to a goal state by minimizing overall cost.

    Core Components

    • A Search*: Explores the state space to find optimal action sequences.
    • Forward Planning: Simulates actions from the start state toward goals.
    • Backward Planning: Optimizes plans by working backward from goals to identify relevant actions.
    • Plan Simulation: Verifies that the generated plan actually achieves the intended goals.
    • Pruning: Removes irrelevant actions to ensure efficient planning.

  8. Use Agentic Tools for LLM orchestration

    main

    Agentic tools use an LLM to decide which sub-tools to call. Embabel provides three types:

    1. SimpleAgenticTool: All sub-tools are available immediately. Best for simple orchestration.
    2. PlaybookTool: Tools are unlocked progressively via prerequisites (other tools, artifacts, blackboard state, or custom predicates).
    3. StateMachineTool: Tools are available based on explicit enum states. Supports state transitions.

  9. Understand Embabel Agent concepts

    main

    In the Embabel framework, an Agent is a self-contained component that bundles domain logic, AI capabilities, and tool usage to achieve specific goals.

    Key characteristics of an Agent:

    • Actions: Agents expose multiple @Action methods. Each method represents a discrete step the agent can take.
    • Inputs/Outputs: Actions take structured or natural language input and return a new type representing the transformation.
    • Execution: During execution, an agent can execute domain code, call AI models, or invoke other agents as sub-processes. It may also trigger side-effects (e.g., database writes, API calls).

  10. Distinguish between Embabel API and SPI

    main

    When developing with Embabel, ensure you distinguish between the public API and the Service Provider Interface (SPI):

    • API (com.embabel.agent.api.*): This is the public interface intended for end-users. Application code should depend exclusively on this package.
    • SPI: This is intended for developers extending Embabel or platform providers. The SPI is subject to change and is not recommended for use in production application code.

  11. Understand WorldState and Planning

    main

    The WorldState represents the current system state as a map of conditions and is the foundation for the Goal-Oriented Action Planning (GOAP) algorithm.

    • WorldState: Used to determine achievable actions and can generate variants with different condition values.
    • Plan: A sequence of Actions created by planners (e.g., AStarGoapPlanner) that represents the lowest-cost path from the current state to the goal state.
    • GoapPlanningSystem: A collection of available Actions and Goals that tracks known preconditions and effects to allow planners to construct valid plans.

  12. Core Concepts of Embabel Agent Framework

    main

    Embabel models agentic flows using four primary building blocks:

    • Actions: The individual steps an agent takes; these are the building blocks of behavior.
    • Goals: The objective an agent is trying to achieve.
    • Conditions: Evaluative criteria used during planning. Conditions are reassessed after every action execution.
    • Domain Model: The objects that underpin the flow and inform Actions, Goals, and Conditions.

    This structure allows Embabel to dynamically formulate a plan (a sequence of actions) that adapts to new information via an OODA loop (Observe, Orient, Decide, Act). Application developers typically do not manage conditions or planning directly; instead, the system infers pre- and post-conditions from the data flow defined in the code.