Embabel Agent

https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/
Admin
Embabel Agent is a JVM-based agentic AI framework that enables sophisticated planning, tool usage,...
Tokens:78,602
Snippets:675
Trust Score:5
Update:9 months ago
Show doc for...
Tokens:
Raw
### Create Typed Object with Examples (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates using `createObject` with strongly typed examples for few-shot prompting. Examples are provided in JSON format to guide the LLM's response generation.

```java
var story = context.ai()
    .withDefaultLlm()
    .withToolGroup(CoreToolGroups.WEB)
    .withExample("A children's story", new Story("Once upon a time..."))
    .creating(Story.class)
    .fromPrompt("Create a story about: " + input.getContent());
```

--------------------------------

### Embael Agent: Add Single Example

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates how to add a single example to an Embael AI agent's request using the `withExample` method. This is useful for providing a specific input-output pair to guide the AI's response. It involves setting up a context, defining an expected plan, and then executing the AI call with the example.

```kotlin
val context = FakeOperationContext.create()
val expectedPlan = ChannelEditPlan(2, "Rhythm")
val example = ObjectCreationExample("Rename channel", expectedPlan)
context.expectResponse(expectedPlan)

val result = context.ai()
    .withDefaultLlm()
    .creating(ChannelEditPlan::class.java)
    .withExample(example)  // Pass the ObjectCreationExample directly
    .fromPrompt("Analyze the edit request")

assertEquals(expectedPlan, result)

```

--------------------------------

### Embael Agent: Add Multiple Examples

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates how to add multiple examples to an Embael AI agent's request using the `withExamples` method, which accepts a list or varargs. This is efficient for providing a broader set of training data to the AI. The example includes verification of the number of prompt contributors to ensure all examples were processed.

```java
@Test
void shouldAddMultipleExamplesFromList() {
    var context = FakeOperationContext.create();
    var expectedPlan = new ChannelEditPlan(1, "Lead Vox");
    context.expectResponse(expectedPlan);

    // Create a list of examples (could be loaded from configuration)
    var examples = List.of(
        new ObjectCreationExample<>("Rename to Bass", new ChannelEditPlan(1, "Bass")),
        new ObjectCreationExample<>("Rename to Drums", new ChannelEditPlan(2, "Drums")),
        new ObjectCreationExample<>("Rename to Keys", new ChannelEditPlan(3, "Keys")),
        new ObjectCreationExample<>("Rename to Vocals", new ChannelEditPlan(4, "Vocals"))
    );

    var result = context.ai()
            .withDefaultLlm()
            .creating(ChannelEditPlan.class)
            .withExamples(examples)  // Pass all examples at once
            .fromPrompt("Analyze the request");

    assertEquals(expectedPlan, result);

    // Verify all examples were added
    var promptContributors = context.getLlmInvocations().getFirst()
            .getInteraction().getPromptContributors();
    assertTrue(promptContributors.size() >= 4);
}

```

```kotlin
@Test
fun `should add multiple examples from list`() {
    val context = FakeOperationContext.create()
    val expectedPlan = ChannelEditPlan(1, "Lead Vox")
    context.expectResponse(expectedPlan)

    // Create a list of examples (could be loaded from configuration)
    val examples = listOf(
        ObjectCreationExample("Rename to Bass", ChannelEditPlan(1, "Bass")),
        ObjectCreationExample("Rename to Drums", ChannelEditPlan(2, "Drums")),
        ObjectCreationExample("Rename to Keys", ChannelEditPlan(3, "Keys")),
        ObjectCreationExample("Rename to Vocals", ChannelEditPlan(4, "Vocals"))
    )

    val result = context.ai()
        .withDefaultLlm()
        .creating(ChannelEditPlan::class.java)
        .withExamples(examples)  // Pass all examples at once
        .fromPrompt("Analyze the request")

    assertEquals(expectedPlan, result)

    // Verify all examples were added
    val promptContributors = context.llmInvocations.first().interaction.promptContributors
    assertTrue(promptContributors.size >= 4)
}

```

```kotlin
val result = context.ai()
    .withDefaultLlm()
    .creating(ChannelEditPlan::class.java)
    .withExamples(
        ObjectCreationExample("Example 1", ChannelEditPlan(1, "Bass")),
        ObjectCreationExample("Example 2", ChannelEditPlan(2, "Drums")),
        ObjectCreationExample("Example 3", ChannelEditPlan(3, "Keys"))
    )
    .fromPrompt("Analyze the request")

```

--------------------------------

### Test Examples with creating() and withExample() in Java

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Tests the `creating()` API by verifying that examples provided via `withExample()` are included in the prompt contributors. This enhances LLM output quality by providing context and desired output formats. The test asserts that at least two examples are correctly added.

```java
@Test
void shouldIncludeExamplesInPrompt() {
    var context = FakeOperationContext.create();
    var expectedPlan = new ChannelEditPlan(1, "Lead Vox");
    context.expectResponse(expectedPlan);

    var result = context.ai()
            .withLlm(llmSelectionService.selectOptimalLlm())
            .withId("analyze-edit-request")
            .creating(ChannelEditPlan.class)
            .withExample("Rename channel 1", new ChannelEditPlan(1, "Bass"))
            .withExample("Rename channel 2", new ChannelEditPlan(2, "Drums"))
            .fromPrompt("Analyze the edit request");

    assertEquals(expectedPlan, result);

    // Verify examples were added as prompt contributors
    var promptContributors = context.getLlmInvocations().getFirst()
            .getInteraction().getPromptContributors();
    assertTrue(promptContributors.size() >= 2, "Examples should be added as prompt contributors");
}
```

--------------------------------

### Test Examples with creating() and withExample() in Kotlin

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Tests the `creating()` API in Kotlin by verifying that examples provided via `withExample()` are included in the prompt contributors. This improves LLM output by giving it context and desired formats. The test asserts that at least two examples are correctly added.

```kotlin
@Test
fun `should include examples in prompt`() {
    val context = FakeOperationContext.create()
    val expectedPlan = ChannelEditPlan(1, "Lead Vox")
    context.expectResponse(expectedPlan)

    val result = context.ai()
        .withLlm(llmSelectionService.selectOptimalLlm())
        .withId("analyze-edit-request")
        .creating(ChannelEditPlan::class.java)
        .withExample("Rename channel 1", ChannelEditPlan(1, "Bass"))
        .withExample("Rename channel 2", ChannelEditPlan(2, "Drums"))
        .fromPrompt("Analyze the edit request")

    assertEquals(expectedPlan, result)

    // Verify examples were added as prompt contributors
    val promptContributors = context.llmInvocations.first().interaction.promptContributors
    assertTrue(promptContributors.size >= 2, "Examples should be added as prompt contributors")
}
```

--------------------------------

### Use ObjectCreationExample for Reusable Examples in Java

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates using the `ObjectCreationExample` data class for defining reusable examples in Java. This promotes cleaner code by allowing examples to be created once and passed to the `creating()` API, improving test maintainability.

```java
@Test
void shouldUseObjectCreationExampleDataClass() {
    var context = FakeOperationContext.create();
    var expectedPlan = new ChannelEditPlan(1, "Lead Vox");
    context.expectResponse(expectedPlan);

    // Create a reusable example using ObjectCreationExample
    var example = new ObjectCreationExample<>(
        "Rename channel example",
        new ChannelEditPlan(2, "Rhythm")
    );

    var result = context.ai()
            .withDefaultLlm()
            .creating(ChannelEditPlan.class)
            .withExample(example)  // Pass the ObjectCreationExample directly
            .fromPrompt("Analyze the edit request");

    assertEquals(expectedPlan, result);
}
```

--------------------------------

### Embael Agent: Full Fluent API Chain Example

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates a comprehensive example of chaining multiple fluent API methods for configuring an Embael AI agent. This includes setting the LLM model, assigning an ID, defining a system prompt, and adding examples, all before executing the prompt. It also includes assertions to verify the configuration settings.

```java
@Test
void shouldTestCompleteFluentApiChain() {
    var context = FakeOperationContext.create();
    var expectedOutput = new ComplexOutput("analysis complete", 42);
    context.expectResponse(expectedOutput);

    // Production code pattern with full fluent API chain
    var result = context.ai()
            .withLlm(LlmOptions.withModel("gpt-4"))
            .withId("complex-analysis")
            .withSystemPrompt("You are an expert analyst")
            .creating(ComplexOutput.class)
            .withExample("Simple case", new ComplexOutput("basic", 1))
            .withExample("Complex case", new ComplexOutput("advanced", 100))
            .fromPrompt("Analyze the input data");

    assertEquals(expectedOutput, result);

    // Comprehensive verification
    var invocation = context.getLlmInvocations().getFirst();
    assertEquals("gpt-4", invocation.getInteraction().getLlm().getModel());
    assertEquals("complex-analysis", invocation.getInteraction().getId().getValue());
    assertTrue(invocation.getInteraction().getPromptContributors().size() >= 3); // system + 2 examples
}

```

--------------------------------

### Use ObjectCreationExample for Reusable Examples in Kotlin

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates using the `ObjectCreationExample` data class for defining reusable examples in Kotlin. This promotes cleaner code by allowing examples to be created once and passed to the `creating()` API, improving test maintainability and reducing redundancy.

```kotlin
@Test
fun `should use ObjectCreationExample data class`() {
    val context = FakeOperationContext.create()
    val expectedPlan = ChannelEditPlan(1, "Lead Vox")
    context.expectResponse(expectedPlan)

    // Create a reusable example using ObjectCreationExample
    val example = ObjectCreationExample(

```

--------------------------------

### Running Rag-Demo Example with EmbaBel

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Provides instructions to run a complete chatbot implementation from the rag-demo project, including setting up data and interacting via a shell. This involves ingesting documents and then initiating a chat.

```bash
./scripts/shell.sh

# In the shell:
ingest ./data/document.md
chat
> What does the document say about...

```

--------------------------------

### Getting Started with RAG

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Instructions on how to integrate RAG into your Embabel Agent application by adding the necessary Maven dependencies.

```APIDOC
## Getting Started with RAG

### Description
To use RAG in your Embabel Agent application, you need to add the `rag-core` module and a specific store implementation to your `pom.xml` file.

### Method
Maven Dependency Management

### Endpoint
N/A

### Parameters
None

### Request Example
```xml
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-rag-lucene</artifactId>
    <version>${embabel.agent.version}</version>
</dependency>

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-rag-tika</artifactId>
    <version>${embabel.agent.version}</version>
</dependency>
```

### Response
N/A (This describes build dependencies, not an API response.)

**Note:** The `embabel-agent-rag-lucene` module provides Lucene-based search, and `embabel-agent-rag-tika` integrates with Apache Tika for document parsing.
```

--------------------------------

### Install Embabel Project Creator with uvx

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

This command installs the Embabel project creator using the 'uvx' command-line tool, which is part of the astral-uv package for Python. It allows for the creation of custom Embabel projects.

```shell
uvx --from git+https://github.com/embabel/project-creator.git project-creator
```

--------------------------------

### Creating and Running Agent Processes with AgentPlatform

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates how to programmatically create an agent process, start it, and retrieve results using the AgentPlatform. This method allows for direct control over agent execution and input binding. It supports both asynchronous and synchronous execution patterns.

```kotlin
val agentProcess = agentPlatform.createAgentProcess(
    agent = myAgent,
    processOptions = ProcessOptions(),
    bindings = mapOf("input" to userRequest)
)

// Start the process and wait for completion
val result = agentPlatform.start(agentProcess).get()

// Or run synchronously
val completedProcess = agentProcess.run()
val result = completedProcess.last<MyResultType>()
```

```kotlin
// Create process from objects (like in web controllers)
val agentProcess = agentPlatform.createAgentProcessFrom(
    agent = travelAgent,
    processOptions = ProcessOptions(),
    travelRequest,
    userPreferences
)
```

--------------------------------

### Java Example - Simple Streaming with Callbacks

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates how to use StreamingPromptRunnerBuilder to stream data with reactive callbacks. It configures a prompt runner, sets a prompt, and processes the streaming events (thinking or object) using doOnNext, doOnError, and doOnComplete. This example utilizes Spring Reactive Programming and expects a MonthItem object.

```java
        PromptRunner runner = ai.withLlm("qwen3:latest")
                                .withToolObject(Tooling.class);

        String prompt = "What are exactly two the most hottest months in Florida and their respective highest temperatures";

        // Use StreamingPromptBuilder instead of Kotlin extension function
        Flux<StreamingEvent<MonthItem>> results = new StreamingPromptRunnerBuilder(runner)
                .withStreaming()
                .withPrompt(prompt)
                .createObjectStreamWithThinking(MonthItem.class);

        // Subscribe with real reactive callbacks using builder pattern
        results
                .timeout(Duration.ofSeconds(150))
                .doOnSubscribe(subscription -> {
                    logger.info("Stream subscription started");
                })
                .doOnNext(event -> {
                    if (event.isThinking()) {
                        String content = event.getThinking();
                        receivedEvents.add("THINKING: " + content);
                        logger.info("Integration test received thinking: {}", content);
                    } else if (event.isObject()) {
                        MonthItem obj = event.getObject();
                        receivedEvents.add("OBJECT: " + obj.getName());
                        logger.info("Integration test received object: {}", obj.getName());
                    }
                })
                .doOnError(error -> {
                    errorOccurred.set(error);
                    logger.info("Integration test stream error: {}", error.getMessage());
                })
                .doOnComplete(() -> {
                    completionCalled.set(true);
                    logger.info("Integration test stream completed successfully");
                })
                .blockLast(Duration.ofSeconds(6000));
```

--------------------------------

### Python Agent: String Outputs and Supervisor

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

This Python example demonstrates an agent where tools return plain strings, requiring the LLM to parse and interpret the results. The supervisor has access to all tools, and the state is managed as a dictionary of messages.

```python
def gather_market_data(topic: str) -> str:
    """Gather market data for a topic."""
    return f"Revenue data for {topic}..."

def analyze_competitors(companies: str) -> str:
    """Analyze competitors."""
    return f"Analysis of {companies}..."

# Create agents with tools
research_agent = create_react_agent(
    model="openai:gpt-4o",
    tools=[gather_market_data, analyze_competitors],
    name="research_expert",
)

# Supervisor sees all tools, always
workflow = create_supervisor([research_agent], model=model)
app = workflow.compile()

# State is a dict of messages
result = app.invoke({"messages": [{"role": "user", "content": "Research cloud market"}]})
```

--------------------------------

### Configuring Agent Invocation with Custom Process Options

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates how to customize agent execution options, such as verbosity settings (showing prompts, responses, and debug information), during agent invocation. Examples are provided for both Java and Kotlin.

```java
var invocation = 
    AgentInvocation.builder(agentPlatform)
        .options(options -> options
            .verbosity(verbosity -> verbosity
                .showPrompts(true)
                .showResponses(true)
                .debug(true)))
        .build(TravelPlan.class);

TravelPlan plan = invocation.invoke(travelRequest);
```

```kotlin
val processOptions = ProcessOptions(
    verbosity = Verbosity(
        showPrompts = true,
        showResponses = true,
        debug = true
    )
)

val invocation: AgentInvocation<TravelPlan> = 
    AgentInvocation.builder(agentPlatform)
        .options(processOptions)
        .build()

val plan = invocation.invoke(travelRequest)
```

--------------------------------

### Generate Text Response with Image Input (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Shows how to generate a text response by providing an image to a vision-capable LLM. This example uses Claude 3.5 Haiku and demonstrates adding a single image to the prompt.

```java
var image = AgentImage.fromFile(imageFile);

var answer = context.ai()
    .withLlm(AnthropicModels.CLAUDE_35_HAIKU)
    .withImage(image)
    .generateText("What is in this image?");
```

--------------------------------

### Built-in helloBanner Tool Output (JSON)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

This is an example of the JSON output from the built-in `helloBanner` tool. It displays server information such as the mode (SYNC), version, Java version, and startup timestamp. This tool is automatically included in every MCP server.

```json
{
  "type": "banner",
  "mode": "SYNC",
  "lines": [
    "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~",
    "Embabel Agent MCP SYNC Server",
    "Version: 0.3.0-SNAPSHOT",
    "Java: 21.0.2+13-LTS-58",
    "Started: 2025-01-17T14:23:47.785Z",
    "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
  ]
}
```

--------------------------------

### Embabel Agent and Action Definition (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates the Embabel equivalent for defining agents and their actions using Java records and annotations. This example showcases type-safe configuration, declarative agent definition, and action execution with LLM integration and tool usage.

```java
@ConfigurationProperties("examples.book-writer")
record BookWriterConfig(
    LlmOptions researcherLlm,
    LlmOptions writerLlm,
    RoleGoalBackstory researcher,
    RoleGoalBackstory writer
) {}

@Agent(description = "Write a book by researching, outlining, and writing chapters")
public record BookWriter(BookWriterConfig config) {

    @Action
    ResearchReport researchTopic(BookRequest request, OperationContext context) {
        return context.ai()
            .withLlm(config.researcherLlm())
            .withPromptElements(config.researcher(), request)
            .withToolGroup(CoreToolGroups.WEB)
            .createObject("Research the topic thoroughly...", ResearchReport.class);
    }

    @Action
    BookOutline createOutline(BookRequest request, ResearchReport research, OperationContext context) {
        return context.ai()
            .withLlm(config.writerLlm())
            .withPromptElements(config.writer(), request, research)
            .createObject("Create a book outline...", BookOutline.class);
    }

    @AchievesGoal(export = @Export(remote = true))
    @Action
    Book writeBook(BookRequest request, BookOutline outline, OperationContext context) {
        // Parallel chapter writing with crew-like coordination
        var chapters = context.parallelMap(outline.chapterOutlines(),
            config.maxConcurrency(),
            chapterOutline -> writeChapter(request, outline, chapterOutline, context));
        return new Book(request, outline.title(), chapters);
    }
}
```

--------------------------------

### Embel Agent: Handling Stuck Actions with StuckHandler (Kotlin)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates implementing the StuckHandler interface in an Embel agent to manage situations where an action gets stuck. The `handleStuck` method is invoked when an agent is stuck, allowing it to add data to the blackboard or replan. This example shows an agent that gets stuck and then un-sticks itself by adding a missing object.

```kotlin
class Dog(val name: String)
class Frog(val name: String)

// Assume AgentProcess, StuckHandler, StuckHandlerResult, StuckHandlingResultCode are defined elsewhere
// Assume AgentProcess.addObject and StuckHandlerResult constructor are available

@Agent(
    description = "self unsticking agent",
)
class SelfUnstickingAgent : StuckHandler {

    var called = false // For testing purposes

    // The agent will get stuck as there's no dog to convert to a frog
    @Action
    @AchievesGoal(description = "the big goal in the sky")
    fun toFrog(dog: Dog): Frog {
        return Frog(dog.name)
    }

    // This method will be called when the agent is stuck
    override fun handleStuck(agentProcess: AgentProcess): StuckHandlerResult {
        called = true
        agentProcess.addObject(Dog("Duke"))
        return StuckHandlerResult(
            message = "Unsticking myself",
            handler = this,
            code = StuckHandlingResultCode.REPLAN,
            agentProcess = agentProcess,
        )
    }
}
```

--------------------------------

### Create Tools Programmatically (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates creating simple tools, tools with parameters, and tools with metadata like direct return capabilities using Embabel's Java factory methods.

```java
// Simple tool with no parameters
Tool greetTool = Tool.create(
    "greet",
    "Greets the user",
    (input) -> Tool.Result.text("Hello!")
);

// Tool with parameters
Tool addTool = Tool.create(
    "add",
    "Adds two numbers together",
    Tool.InputSchema.of(
        new Tool.Parameter("a", Tool.ParameterType.INTEGER, "First number", true, null),
        new Tool.Parameter("b", Tool.ParameterType.INTEGER, "Second number", true, null)
    ),
    (input) -> {
        // Parse input JSON and compute result
        return Tool.Result.text("42");
    }
);

// Tool with metadata (e.g., return directly without LLM processing)
Tool directTool = Tool.create(
    "lookup",
    "Looks up data directly",
    Tool.Metadata.create(true), // returnDirect = true
    (input) -> Tool.Result.text("Direct result")
);
```

--------------------------------

### Create Tools Programmatically (Kotlin)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Shows how to create tools using Embabel's Kotlin DSL, including simple tools, tools with parameters, and tools configured for direct returns.

```kotlin
// Simple tool with no parameters
val greetTool = Tool.of(
    name = "greet",
    description = "Greets the user"
) { _ ->
    Tool.Result.text("Hello!")
}

// Tool with parameters
val addTool = Tool.of(
    name = "add",
    description = "Adds two numbers together",
    inputSchema = Tool.InputSchema.of(
        Tool.Parameter("a", Tool.ParameterType.INTEGER, "First number", true, null),
        Tool.Parameter("b", Tool.ParameterType.INTEGER, "Second number", true, null)
    )
) { input ->
    // Parse input JSON and compute result
    Tool.Result.text("42")
}

// Tool with metadata
val directTool = Tool.of(
    name = "lookup",
    description = "Looks up data directly",
    metadata = Tool.Metadata(returnDirect = true)
) { _ ->
    Tool.Result.text("Direct result")
}
```

--------------------------------

### Embabel SKILL.md YAML Frontmatter and Instructions

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates the YAML frontmatter for defining skill metadata (name, description, license, compatibility) and the structure for providing step-by-step instructions within the SKILL.md file.

```markdown
---
name: my-skill
description: A skill that does something useful
license: Apache-2.0
compatibility: Requires Python 3.9+
---

# My Skill Instructions

Step-by-step instructions for using this skill...
```

--------------------------------

### Interact with Embabel Agent via Shell

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Example command to interact with a running Embabel agent through the shell interface. The input is processed by the agent, demonstrating its functionality.

```bash
x "Tell me a story about a robot learning to paint"
```

--------------------------------

### Configure Action Cost and Value

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

This example shows how to define the 'cost' and 'value' parameters for an @Action. These parameters range from 0.0 to 1.0, where lower cost is cheaper and higher value is more desirable. The utility planner uses these to calculate the net value (value - cost) for action selection.

```kotlin
@Action(
    cost = 0.1,
    value = 0.8
)
fun highValueAction(input: Input): Output {
    // Action implementation
}
```

--------------------------------

### Docling Command Line Tool

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

A command-line example using Docling to convert a PDF document to Markdown. This is recommended for complex documents to improve parsing and chunking quality.

```bash
docling https://example.com/document.pdf --from pdf --to md --output ./data
```

--------------------------------

### Create a Simple Agent using SimpleAgentBuilder

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates creating a basic agent using the SimpleAgentBuilder. This builder is suitable for simple agent creation without preconditions or postconditions. It specifies the return type, the action to run, and builds the agent with a name and description.

```java
var agent = SimpleAgentBuilder
    .returning(Joke.class) 
    .running(tac -> tac.ai() 
        .withDefaultLlm()
        .createObject("Tell me a joke", Joke.class))
    .buildAgent("joker", "This is guaranteed to return a dreadful joke");
```

--------------------------------

### Export Multiple Tool Sources with Different Prefixes (Kotlin)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

This example shows how to export tools from multiple sources, each with its own unique naming strategy. It uses `McpToolExport.fromToolObjects` to combine different `ToolObject` instances, each configured with a specific prefix strategy. This allows for organized namespacing when dealing with tools from disparate origins.

```kotlin
@Bean
fun multiSourceTools(): McpToolExport {
    return McpToolExport.fromToolObjects(
        listOf(
            ToolObject(
                objects = listOf(weatherTools),
                namingStrategy = { "weather_$it" }
            ),
            ToolObject(
                objects = listOf(stockTools),
                namingStrategy = { "stocks_$it" }
            )
        )
    )
}
```

--------------------------------

### Document Ingestion Method (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

An example shell method for ingesting documents from a given location (URL or file path). It uses TikaHierarchicalContentReader and NeverRefreshExistingDocumentContentPolicy to handle parsing and ingestion.

```java
@ShellMethod("Ingest URL or file path")
String ingest(@ShellOption(defaultValue = "./data/document.md") String location) {
    var uri = location.startsWith("http://") || location.startsWith("https://")
            ? location
            : Path.of(location).toAbsolutePath().toUri().toString();
    var ingested = NeverRefreshExistingDocumentContentPolicy.INSTANCE
            .ingestUriIfNeeded(
                    luceneSearchOperations,
                    new TikaHierarchicalContentReader(),
                    uri
            );
    return ingested != null ?
            "Ingested document with ID: " + ingested :
            "Document already exists, no ingestion performed.";
}
```

--------------------------------

### Obtain and Use PromptRunner

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates how to obtain a PromptRunner from an OperationContext to execute LLM calls. It shows how to get a runner with the default LLM or a custom one configured with specific LlmOptions.

```java
@Action
public Story createStory(UserInput input, OperationContext context) {
    // Get PromptRunner with default LLM
    var runner = context.ai().withDefaultLlm();

    // Get PromptRunner with specific LLM options
    var customRunner = context.ai().withLlm(
        LlmOptions.withModel(OpenAiModels.GPT_4O_MINI)
            .withTemperature(0.8)
    );

    return customRunner.createObject("Write a story about: " + input.getContent(), Story.class);
}
```

--------------------------------

### Define Actions with @EmbabelComponent

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

This example demonstrates how to define actions using the @EmbabelComponent annotation. It shows how to create a component that contributes actions to the platform, how output bindings work, how to add entities to the context, and how to control action execution through preconditions (e.g., SpEL). Returning null prevents subsequent actions.

```kotlin
@EmbabelComponent
class IssueActions(
    val properties: ShepherdProperties,
    private val communityDataManager: CommunityDataManager,
    private val gitHubUpdater: GitHubUpdater,
) {

    @Action(outputBinding = "ghIssue")
    fun saveNewIssue(ghIssue: GHIssue, context: OperationContext): GHIssue? {
        val existing = communityDataManager.findIssueByGithubId(ghIssue.id)
        if (existing == null) {
            val issueEntityStatus = communityDataManager.saveAndExpandIssue(ghIssue)
            context += issueEntityStatus
            return ghIssue
        }
        return null
    }

    @Action(
        pre = ["spel:newEntity.newEntities.?[#this instanceof T(com.embabel.shepherd.domain.Issue)].size() > 0"]
    )
    fun reactToNewIssue(
        ghIssue: GHIssue,
        newEntity: NewEntity<*>,
        ai: Ai
    ): IssueAssessment {
        return ai
            .withLlm(properties.triageLlm)
            .creating(IssueAssessment::class.java)
            .fromTemplate("first_issue_response", mapOf("issue" to ghIssue))
    }

    @Action(pre = ["spel:issueAssessment.urgency > 0.0"])
    fun heavyHitterIssue(issue: GHIssue, issueAssessment: IssueAssessment) {
        // Take action on high-urgency issues
    }
}
```

--------------------------------

### Agent Invocation with Named Inputs

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Shows how to invoke an agent using a map of named inputs. This approach is useful when an agent expects multiple, specifically named parameters. The example demonstrates this functionality in Java.

```java
// Invoke with a map of named inputs
Map<String, Object> inputs = Map.of(
    "request", travelRequest,
    "preferences", userPreferences
);

TravelPlan plan = invocation.invoke(inputs);
```

--------------------------------

### Initialize and Use Skills with PromptRunner (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

This Java code demonstrates how to initialize a 'Skills' object for financial analysis and load skills from a GitHub URL. It then uses this 'skills' object as a reference with a 'PromptRunner' to enable an AI to act as a financial analyst.

```java
var skills = new Skills("financial-skills", "Financial analysis skills")
    .withGitHubUrl("https://github.com/wshobson/agents/tree/main/plugins/business-analytics/skills");

var response = context.ai()
    .withLlm(llm)
    .withReference(skills)
    .withSystemPrompt("You are a helpful financial analyst.")
    .respond(conversation.getMessages());
```

--------------------------------

### Implement Custom RAG Store - Vector Search Only

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Example of implementing a custom RAG store that only supports vector search. This adheres to the principle of implementing only the interfaces that are natural and efficient for the store's capabilities.

```kotlin
// A store that only supports vector search
class MyVectorOnlyStore : VectorSearch {
    override fun <T : Retrievable> vectorSearch(
        request: TextSimilaritySearchRequest,
        clazz: Class<T>,
    ): List<SimilarityResult<T>> {
        // Implement vector similarity search
    }
}
```

--------------------------------

### Bind Customer Data to AgentProcess using @LlmTool (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates how a tool method can access the current AgentProcess to bind data, such as a customer object retrieved by ID, to the process's blackboard. This allows other actions within the same process to access this data. It uses `AgentProcess.get()` to retrieve the process instance.

```java
@LlmTool(description="My Tool") String bindCustomer(Long id) {
var customer = customerRepository.findById(id);
var agentProcess = AgentProcess.get();
if (agentProcess != null) {
agentProcess.addObject(customer);
return "Customer bound to blackboard";
}
return "No agent process: Unable to bind customer";
}

```

--------------------------------

### Create Chatbot Action Method in Java

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

An example of an action method within an @EmbabelComponent class designed to respond to user messages. It utilizes a ToolishRag for information retrieval and sends an assistant message back to the conversation.

```java
@EmbabelComponent
public class ChatActions {

    private final ToolishRag toolishRag;
    private final RagbotProperties properties;

    public ChatActions(
            SearchOperations searchOperations,
            RagbotProperties properties) {
        this.toolishRag = new ToolishRag(
                "sources",
                "Sources for answering user questions",
                searchOperations
        );
        this.properties = properties;
    }

    @Action(canRerun = true, trigger = UserMessage.class)
    void respond(
            Conversation conversation,
            ActionContext context) {
        var assistantMessage = context.ai()
                .withLlm(properties.chatLlm())
                .withReference(toolishRag)
                .withTemplate("ragbot")
                .respondWithSystemPrompt(conversation, Map.of(
                        "properties", properties
                ));
        context.sendMessage(conversation.addMessage(assistantMessage));
    }
}
```

--------------------------------

### Explicit Binding Example - Java

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates how to explicitly bind objects to the Blackboard using the `context.bind()` method. This is used when you want to assign a specific name to a blackboard item, which is useful for situations when there are multiple candidates of the same type.

```java
@Action
public Person extractPerson(UserInput userInput, OperationContext context) {
    PersonImpl maybeAPerson = context.promptRunner().withLlm(LlmOptions.fromModel(OpenAiModels.GPT_41)).createObjectIfPossible(
            """
            Create a person from this user input, extracting their name:
            %s""".formatted(userInput.getContent()),
            PersonImpl.class
    );
    if (maybeAPerson != null) {
        context.bind("user", maybeAPerson);
    }
    return maybeAPerson;
}
```

--------------------------------

### Create Agentic Tool with Sub-Tools (Java)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Demonstrates creating sub-tools for basic math operations and then composing them into an agentic tool named 'math-orchestrator'. This tool is configured with specific LLM settings and a system prompt to guide its orchestration. It is then used within a context to generate text for a mathematical query.

```java
Tool addTool = Tool.create("add", "Adds two numbers", input -> {
    // Parse JSON input and compute result
    return Tool.Result.text("5");
});

Tool multiplyTool = Tool.create("multiply", "Multiplies two numbers", input -> {
    return Tool.Result.text("6");
});

// Create the agentic tool
AgenticTool mathOrchestrator = new AgenticTool("math-orchestrator", "Orchestrates math operations")
    .withTools(addTool, multiplyTool)
    .withLlm(LlmOptions.withModel("gpt-4"))
    .withSystemPrompt("Use the available tools to solve the given math problem");

// Use it like any other tool
context.ai()
    .withDefaultLlm()
    .withTool(mathOrchestrator)
    .generateText("What is 5 + 3 * 2?");
```

--------------------------------

### Python Agent Definition with Supervisor Planner (LangGraph)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates how a similar workflow might be structured in LangGraph using Python. This snippet shows the basic setup for creating a supervisor agent within the LangGraph framework.

```python
from langgraph_supervisor import create_supervisor
from langgraph.prebuilt import create_react_agent

```

--------------------------------

### Create Agentic Tool with Sub-Tools (Kotlin)

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates the creation of sub-tools for mathematical operations in Kotlin, followed by their integration into an agentic tool called 'math-orchestrator'. The agentic tool is configured with LLM parameters and a custom system prompt to manage task execution. Finally, it shows how to invoke this agentic tool within a context to process a mathematical question.

```kotlin
// Create sub-tools
val addTool = Tool.of("add", "Adds two numbers") { input ->
    // Parse JSON input and compute result
    Tool.Result.text("5")
}

val multiplyTool = Tool.of("multiply", "Multiplies two numbers") { input ->
    Tool.Result.text("6")
}

// Create the agentic tool
val mathOrchestrator = AgenticTool("math-orchestrator", "Orchestrates math operations")
    .withTools(addTool, multiplyTool)
    .withLlm(LlmOptions(model = "gpt-4"))
    .withSystemPrompt("Use the available tools to solve the given math problem")

// Use it like any other tool
context.ai()
    .withDefaultLlm()
    .withTool(mathOrchestrator)
    .generateText("What is 5 + 3 * 2?")
```

--------------------------------

### Implement Custom RAG Store - Vector and Text Search

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Example of implementing a custom RAG store that supports both vector search and full-text search. This demonstrates implementing multiple interfaces to leverage different search capabilities.

```kotlin
// A store that supports both vector and text search
class MyFullTextStore : VectorSearch, TextSearch {
    override fun <T : Retrievable> vectorSearch(
        request: TextSimilaritySearchRequest,
        clazz: Class<T>,
    ): List<SimilarityResult<T>> {
        // Implement vector similarity search
    }

    override fun <T : Retrievable> textSearch(
        request: TextSimilaritySearchRequest,
        clazz: Class<T>,
    ): List<SimilarityResult<T>> {
        // Implement full-text search
    }

    override val luceneSyntaxNotes: String = "Full Lucene syntax supported"
}
```

--------------------------------

### Kotlin Agent: Blackboard-Driven Tool Filtering Example

Source: https://docs.embabel.com/embabel-agent/guide/0.3.2-SNAPSHOT/index

Illustrates how Embabel's supervisor filters available tools based on the content of the typed blackboard. Tools whose input requirements are met by existing blackboard artifacts are prioritized, simplifying the LLM's decision-making process.

```kotlin
# Initial state: empty blackboard
Available tools:
- gatherMarketData(request: MarketDataRequest) -> MarketData
- analyzeCompetitors(request: CompetitorAnalysisRequest) -> CompetitorAnalysis

# After MarketData is gathered:
Available tools:
- gatherMarketData(request: MarketDataRequest) -> MarketData  [READY - 0 params needed]
- analyzeCompetitors(request: CompetitorAnalysisRequest) -> CompetitorAnalysis
```
Tokens:
Raw