Embabel Agent

https://docs.embabel.com/embabel-agent/guide/0.1.3
Admin
Embabel Agent is a framework for building sophisticated, goal-driven AI agents on the JVM, enabling...
Tokens:18,394
Snippets:201
Trust Score:5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Add Few-Shot Examples to PromptRunner

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Shows how to include examples in the prompt to guide the LLM's output format.

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

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

### Clone and run Embabel examples

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Commands to clone the examples repository and launch the shell script for Java or Kotlin.

```bash
# Clone and run examples
git clone https://github.com/embabel/embabel-agent-examples
cd embabel-agent-examples/scripts/java
./shell.sh
```

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

### Configure Gradle Repositories and Dependencies

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Setup repositories and dependencies for both Kotlin and Groovy DSL Gradle builds.

```kotlin
repositories {
    mavenCentral()
    maven {
        name = "embabel-releases"
        url = uri("https://repo.embabel.com/artifactory/libs-release")
        mavenContent {
            releasesOnly()
        }
    }
    maven {
        name = "embabel-snapshots"
        url = uri("https://repo.embabel.com/artifactory/libs-snapshot")
        mavenContent {
            snapshotsOnly()
        }
    }
    maven {
        name = "Spring Milestones"
        url = uri("https://repo.spring.io/milestone")
    }
}

dependencies {
    implementation("com.embabel.agent:embabel-agent-starter-shell:${embabel-agent.version}")
}
```

```groovy
repositories {
    mavenCentral()
    maven {
        name = 'embabel-releases'
        url = 'https://repo.embabel.com/artifactory/libs-release'
        mavenContent {
            releasesOnly()
        }
    }
    maven {
        name = 'embabel-snapshots'
        url = 'https://repo.embabel.com/artifactory/libs-snapshot'
        mavenContent {
            snapshotsOnly()
        }
    }
    maven {
        name = 'Spring Milestones'
        url = 'https://repo.spring.io/milestone'
    }
}

dependencies {
    implementation 'com.embabel.agent:embabel-agent-starter-shell:${embabel-agent.version}'
}
```

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

### Example shell commands

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Common commands to test horoscope, research, and fact-checking agents.

```bash
# Simple horoscope agent
execute "My name is Sarah and I'm a Leo"

# Research with web tools (requires Docker Desktop with MCP extension)
execute "research the recent australian federal election. what is the position of the Greens party?"

# Fact checking
x "fact check the following: holden cars are still made in australia"
```

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

### Implement Embabel Agent and Configuration

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Example of using Spring ConfigurationProperties and Embabel's @Agent annotation to define a type-safe, coordinated multi-step process.

```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);
    }
}
```

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

### Define a WriteAndReviewAgent

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Example of an agent class using @Agent, @Action, and @AchievesGoal annotations to orchestrate LLM interactions.

```java
@Agent(description = "Agent that writes and reviews stories")
public class WriteAndReviewAgent {

    @Action
    public Story writeStory(UserInput userInput, OperationContext context) {
        return context.ai()
            .withAutoLlm()
            .createObject("""
                You are a creative writer who aims to delight and surprise.
                Write a story about %s
                """.formatted(userInput.getContent()),
            Story.class);
    }

    @AchievesGoal(description = "Review a story")
    @Action
    public ReviewedStory reviewStory(Story story, OperationContext context) {
        return context.ai()
            .withLlmByRole("reviewer")
            .createObject("""
                You are a meticulous editor.
                Carefully review this story:
                %s
            ".formatted(story.text),
            ReviewedStory.class);
    }
}
```

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

### Define CrewAI Agents and Crew

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Example of defining agents with roles, goals, and backstories, then coordinating them in a sequential process using CrewAI.

```python
research_agent = Agent(
    role='Research Specialist',
    goal='Find comprehensive information',
    backstory='Expert researcher with 10+ years experience'
)

writer_agent = Agent(
    role='Content Writer',
    goal='Create engaging content',
    backstory='Professional writer specializing in technical content'
)

crew = Crew(
    agents=[research_agent, writer_agent],
    tasks=[research_task, write_task],
    process=Process.sequential
)
```

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

### Integration Testing with EmbabelMockitoIntegrationTest

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Example of a test class extending EmbabelMockitoIntegrationTest to verify a complete agent workflow using mock stubbing and verification methods.

```java
/**
* Use framework superclass to test the complete workflow of writing and reviewing a story.
* This will run under Spring Boot against an AgentPlatform instance * that has loaded all our agents.
*/ class StoryWriterIntegrationTest extends EmbabelMockitoIntegrationTest {

    @Test
    void shouldExecuteCompleteWorkflow() {
        var input = new UserInput("Write about artificial intelligence");

        var story = new Story("AI will transform our world...");
        var reviewedStory = new ReviewedStory(story, "Excellent exploration of AI themes.", Personas.REVIEWER);

        whenCreateObject(contains("Craft a short story"), Story.class)
                .thenReturn(story);

        // The second call uses generateText
        whenGenerateText(contains("You will be given a short story to review"))
                .thenReturn(reviewedStory.review());

        var invocation = AgentInvocation.create(agentPlatform, ReviewedStory.class);
        var reviewedStoryResult = invocation.invoke(input);

        assertNotNull(reviewedStoryResult);
        assertTrue(reviewedStoryResult.getContent().contains(story.text()),
                "Expected story content to be present: " + reviewedStoryResult.getContent());
        assertEquals(reviewedStory, reviewedStoryResult,
                "Expected review to match: " + reviewedStoryResult);

        verifyCreateObjectMatching(prompt -> prompt.contains("Craft a short story"), Story.class,
                llm -> llm.getLlm().getTemperature() == 0.9 && llm.getToolGroups().isEmpty());
        verifyGenerateTextMatching(prompt -> prompt.contains("You will be given a short story to review"));
        verifyNoMoreInteractions();
    }
}
```

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

### Define a Pydantic AI support agent

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Example of a Pydantic AI agent using system prompts and tool decorators for bank support.

```python
# Based on https://ai.pydantic.dev/examples/bank-support/
from pydantic_ai import Agent, RunContext
from pydantic_ai.tools import tool

@system_prompt
def support_prompt() -> str:
    return "You are a support agent in our bank"

@tool
async def get_customer_balance(customer_id: int, include_pending: bool = False) -> float:
    # Database lookup
    customer = find_customer(customer_id)
    return customer.balance + (customer.pending if include_pending else 0)

agent = Agent(
    'openai:gpt-4-mini',
    system_prompt=support_prompt,
    tools=[get_customer_balance],
)

result = agent.run("What's my balance?", deps={'customer_id': 123})
```

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

### Initialize a custom project with the project creator

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Use the project creator tool via uvx to scaffold a new Embabel Agent project.

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

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

### Configure LlmOptions

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates creating LlmOptions with specific models and hyperparameters like temperature and top-P.

```java
// Create LlmOptions with model and temperature
var options = LlmOptions.withModel(OpenAiModels.GPT_4O_MINI)
    .withTemperature(0.8);

// Use different hyperparameters for different tasks
var analyticalOptions = LlmOptions.withModel(OpenAiModels.GPT_4O_MINI)
    .withTemperature(0.2)
    .withTopP(0.9);
```

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

### Create and Execute AgentProcess Programmatically

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates creating an agent process with bindings and executing it either asynchronously or synchronously.

```kotlin
// Create an agent process with bindings
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>()
```

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

### Configure and run the agent shell

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Set the required API key and launch the agent shell environment.

```bash
export OPENAI_API_KEY="your_key_here"
./scripts/shell.sh
```

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

### Create Custom Tool Group Configurations

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Shows how to implement custom configuration classes to expose domain-specific tool groups using dependency injection.

```java
@Configuration
public class MyToolGroupsConfiguration {

    @Bean
    public ToolGroup databaseToolsGroup(DataSource dataSource) {
        return new DatabaseToolGroup(dataSource);
    }

    @Bean
    public ToolGroup emailToolsGroup(EmailService emailService) {
        return new EmailToolGroup(emailService);
    }
}
```

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

### Implement a Stateful Tool

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates using the @Tool annotation and accessing the AgentProcess to bind objects to the blackboard.

```java
@Tool(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";
}
```

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

### Configure Tool Groups with Spring

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates using a Spring configuration class to inject MCP clients and define a tool group with specific filtering logic.

```kotlin
@Configuration
class ToolGroupsConfiguration(
    private val mcpSyncClients: List<McpSyncClient>,
) {

    @Bean
    fun mathToolGroup() = MathTools()

    @Bean
    fun mcpWebToolsGroup(): ToolGroup {
        return McpToolGroup(
            description = CoreToolGroups.WEB_DESCRIPTION,
            name = "docker-web",
            provider = "Docker",
            permissions = setOf(ToolGroupPermission.INTERNET_ACCESS),
            clients = mcpSyncClients,
            filter = {
                // Only expose specific web tools, exclude rate-limited ones
                (it.toolDefinition.name().contains("brave") ||
                 it.toolDefinition.name().contains("fetch")) &&
                !it.toolDefinition.name().contains("brave_local_search")
            }
        )
    }
}
```

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

### Perform Blackboard Operations

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates adding objects, retrieving them by type, and managing boolean conditions within the blackboard.

```kotlin
// Add objects to blackboard
blackboard += person
blackboard["result"] = analysis

// Retrieve objects by type
val person = blackboard.last<Person>()
val allPersons = blackboard.all<Person>()

// Check conditions
blackboard.setCondition("userVerified", true)
val verified = blackboard.getCondition("userVerified")
```

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

### Configure Environment Variables

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Define required API keys in a .env file for LLM provider authentication.

```text
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
```

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

### Create Typed Objects with PromptRunner

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates the fluent API for creating typed objects from prompts, including the use of tool groups.

```java
var story = context.ai()
    .withDefaultLlm()
    .withToolGroup(CoreToolGroups.WEB)
    .creating(Story.class)
    .fromPrompt("Create a story about: " + input.getContent());
```

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

### Implement Custom Prompt Contributors

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates creating custom prompt contributors by implementing the PromptContributor interface for specific system or conditional logic.

```kotlin
class CustomSystemPrompt(private val systemName: String) : PromptContributor {
    override fun contribution(): String {
        return "System: $systemName - Current time: ${LocalDateTime.now()}"
    }
}

class ConditionalPrompt(
    private val condition: () -> Boolean,
    private val trueContent: String,
    private val falseContent: String
) : PromptContributor {
    override fun contribution(): String {
        return if (condition()) trueContent else falseContent
    }
}
```

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

### Configure Tools at PromptRunner Level

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Apply tool groups directly to a PromptRunner instance for more granular control over tool availability per prompt.

```kotlin
// Add tool groups to a specific prompt
context.promptRunner().withToolGroup(CoreToolGroups.WEB).create(
    """
    Given the topic, generate a detailed report using web research.

    # Topic
    ${reportRequest.topic}
    """.trimIndent()
)

// Add multiple tool groups
context.ai().withDefaultLlm()
    .withToolGroup(CoreToolGroups.WEB)
    .withToolGroup(CoreToolGroups.MATH)
    .createObject("Calculate stock performance with web data", StockReport::class)
```

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

### Add Embabel Agent Maven Dependencies

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Include the desired starter dependency in your pom.xml file based on your application's requirements.

```xml
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-shell</artifactId>
    <version>${embabel-agent.version}</version>
</dependency>
```

```xml
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-mcpserver</artifactId>
    <version>${embabel-agent.version}</version>
</dependency>
```

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

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

### Obtain and Use PromptRunner

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Shows how to retrieve a PromptRunner from an OperationContext and execute a prompt to create a typed object.

```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);
}
```

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

### Configure Maven Repositories

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Add the necessary Embabel and Spring repositories to your pom.xml to resolve dependencies.

```xml
<repositories>
    <repository>
        <id>embabel-releases</id>
        <url>https://repo.embabel.com/artifactory/libs-release</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>embabel-snapshots</id>
        <url>https://repo.embabel.com/artifactory/libs-snapshot</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-milestones</id>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>
```

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

### Create Object with Jinja Template

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Uses a Jinja template from the classpath to create an object via PromptRunner.

```kotlin
val distinctFactualAssertions = context.ai()
    .withLlm(properties.deduplicationLlm())
    // Jinjava template from classpath at prompts/factchecker/consolidate_assertions.jinja
    .withTemplate("factchecker/consolidate_assertions")
    .createObject(
            DistinctFactualAssertions.class,
            Map.of(
                    "assertions", allAssertions,
                    "reasoningWordCount", properties.reasoningWordCount()
            )
    );
```

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

### Enable Debug Logging

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Configure application logging to output detailed information from the Embabel agent package.

```yaml
logging:
  level:
    com.embabel.agent: DEBUG
```

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

### Implement a complex workflow with ScatterGatherBuilder

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates a parallel processing pattern that gathers results from multiple LLM calls and consolidates them into a single result.

```java
@Action
FactChecks runAndConsolidateFactChecks(
        DistinctFactualAssertions distinctFactualAssertions,
        ActionContext context) {
    var llmFactChecks = properties.models().stream()
            .flatMap(model -> factCheckWithSingleLlm(model, distinctFactualAssertions, context))
            .toList();
    return ScatterGatherBuilder __**(1)**
            .returning(FactChecks.class) __**(2)**
            .fromElements(FactCheck.class) __**(3)**
            .generatedBy(llmFactChecks) __**(4)**
            .consolidatedBy(this::reconcileFactChecks) __**(5)**
            .asSubProcess(context); __**(6)**
    }
```

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

### Create AgentProcess from Varargs

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Creates an agent process by passing objects directly as varargs to populate the input map.

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

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

### Set API keys for Embabel

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Environment variables required for authentication with OpenAI or Anthropic services.

```bash
export OPENAI_API_KEY="your_openai_key"
export ANTHROPIC_API_KEY="your_anthropic_key"
```

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

### Execute agent command in shell

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Run an agent flow using the execute command with prompt and response logging enabled.

```bash
execute "Lynda is a Scorpio, find news for her" -p -r
```

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

### Test WriteAndReviewAgent in Java

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Uses FakeOperationContext to verify prompt content and LLM temperature settings for a story-writing agent.

```java
class WriteAndReviewAgentTest {

    @Test
    void testWriteAndReviewAgent() {
        var context = FakeOperationContext.create();
        var promptRunner = (FakePromptRunner) context.promptRunner();
        context.expectResponse(new Story("One upon a time Sir Galahad . . "));

        var agent = new WriteAndReviewAgent(200, 400);
        agent.craftStory(new UserInput("Tell me a story about a brave knight", Instant.now()), context);

        String prompt = promptRunner.getLlmInvocations().getFirst().getPrompt();
        assertTrue(prompt.contains("knight"), "Expected prompt to contain 'knight'");

        var temp = promptRunner.getLlmInvocations().getFirst().getInteraction().getLlm().getTemperature();
        assertEquals(0.9, temp, 0.01,
                "Expected temperature to be 0.9: Higher for more creative output");
    }

    @Test
    void testReview() {
        var agent = new WriteAndReviewAgent(200, 400);
        var userInput = new UserInput("Tell me a story about a brave knight", Instant.now());
        var story = new Story("Once upon a time, Sir Galahad...");
        var context = FakeOperationContext.create();
        context.expectResponse("A thrilling tale of bravery and adventure!");
        agent.reviewStory(userInput, story, context);

        var promptRunner = (FakePromptRunner) context.promptRunner();
        String prompt = promptRunner.getLlmInvocations().getFirst().getPrompt();
        assertTrue(prompt.contains("knight"), "Expected review prompt to contain 'knight'");
        assertTrue(prompt.contains("review"), "Expected review prompt to contain 'review'");
    }
}
```

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

### Create a Persona

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Defines an AI agent's personality, voice, and objective using the Persona convenience class.

```kotlin
val persona = Persona.create(
    name = "Alex the Analyst",
    persona = "A detail-oriented data analyst with expertise in financial markets",
    voice = "Professional yet approachable, uses clear explanations",
    objective = "Help users understand complex financial data through clear analysis"
)
```

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

### Define an Embabel Agent with Multi-Step Actions

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

This class demonstrates an agent that uses Spring dependency injection for services and @Action annotations to define steps that infer preconditions and postconditions based on method signatures.

```java
@Agent(description = "Find news based on a person's star sign")  __**(1)**
public class StarNewsFinder {

    private final HoroscopeService horoscopeService;  __**(2)**
    private final int storyCount;

    public StarNewsFinder(
            HoroscopeService horoscopeService,  __**(3)**
            @Value("${star-news-finder.story.count:5}") int storyCount) {
        this.horoscopeService = horoscopeService;
        this.storyCount = storyCount;
    }

    @Action  __**(4)**
    public StarPerson extractStarPerson(UserInput userInput, OperationContext context) {  __**(5)**
        return context.ai()
            .withLlm(OpenAiModels.GPT_41)
            .createObject("""
                Create a person from this user input, extracting their name and star sign:
                %s""".formatted(userInput.getContent()), StarPerson.class);  __**(6)**
    }

    @Action  __**(7)**
    public Horoscope retrieveHoroscope(StarPerson starPerson) {  __**(8)**
        // Uses regular injected Spring service - not LLM
        return new Horoscope(horoscopeService.dailyHoroscope(starPerson.sign()));  __**(9)**
    }

    @Action(toolGroups = {CoreToolGroups.WEB})  __**(10)**
    public RelevantNewsStories findNewsStories(
            StarPerson person, Horoscope horoscope, OperationContext context) {  __**(11)**
        var prompt = """
            %s is an astrology believer with the sign %s.
            Their horoscope for today is: %s
            Given this, use web tools to find %d relevant news stories.
            """.formatted(person.name(), person.sign(), horoscope.summary(), storyCount);

        return context.ai().withDefaultLlm().createObject(prompt, RelevantNewsStories.class);  __**(12)**
    }

    @AchievesGoal(description = "Write an amusing writeup based on horoscope and news")  __**(13)**
    @Action
    public Writeup writeup(
            StarPerson person, RelevantNewsStories stories, Horoscope horoscope,
            OperationContext context) {  __**(14)**
        var llm = LlmOptions.fromCriteria(ModelSelectionCriteria.getAuto())
            .withTemperature(0.9);  __**(15)**

        var prompt = """
            Write something amusing for %s based on their horoscope and these news stories.
            Format as Markdown with links.
            """.formatted(person.name());

        return context.ai().withLlm(llm).createObject(prompt, Writeup.class);  __**(16)**
    }
}
```

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

### Define Role, Goal, and Backstory

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Uses the RoleGoalBackstory class to structure agent identity, following patterns similar to Crew AI.

```kotlin
var agent = RoleGoalBackstory.withRole("Senior Software Engineer")
    .andGoal("Write clean, maintainable code")
    .andBackstory("10+ years experience in enterprise software development")
```

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

### Test WriteAndReviewAgent in Kotlin

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Uses FakeOperationContext to verify prompt content and LLM temperature settings in a Kotlin environment.

```kotlin
/**
 * Unit tests for the WriteAndReviewAgent class.
 * Tests the agent's ability to craft and review stories based on user input.
 */
internal class WriteAndReviewAgentTest {

    /**
     * Tests the story crafting functionality of the WriteAndReviewAgent.
     * Verifies that the LLM call contains expected content and configuration.
     */
    @Test
    fun testCraftStory() {
        // Create agent with word limits: 200 min, 400 max
        val agent = WriteAndReviewAgent(200, 400)
        val context = FakeOperationContext.create()
        val promptRunner = context.promptRunner() as FakePromptRunner

        context.expectResponse(Story("One upon a time Sir Galahad . . "))

        agent.craftStory(
            UserInput("Tell me a story about a brave knight", Instant.now()),
            context
        )

        // Verify the prompt contains the expected keyword
        Assertions.assertTrue(
            promptRunner.llmInvocations.first().prompt.contains("knight"),
            "Expected prompt to contain 'knight'"
        )

        // Verify the temperature setting for creative output
        val actual = promptRunner.llmInvocations.first().interaction.llm.temperature
        Assertions.assertEquals(
            0.9, actual, 0.01,
            "Expected temperature to be 0.9: Higher for more creative output"
        )
    }

    @Test
    fun testReview() {
        val agent = WriteAndReviewAgent(200, 400)
        val userInput = UserInput("Tell me a story about a brave knight", Instant.now())
        val story = Story("Once upon a time, Sir Galahad...")
        val context = FakeOperationContext.create()

        context.expectResponse("A thrilling tale of bravery and adventure!")
        agent.reviewStory(userInput, story, context)

        val promptRunner = context.promptRunner() as FakePromptRunner
        val prompt = promptRunner.llmInvocations.first().prompt
        Assertions.assertTrue(prompt.contains("knight"), "Expected review prompt to contain 'knight'")
        Assertions.assertTrue(prompt.contains("review"), "Expected review prompt to contain 'review'")

        // Verify single LLM invocation during review
        Assertions.assertEquals(1, promptRunner.llmInvocations.size)
    }
}
```

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

### Implement custom Spring Shell command

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Create a custom shell component by injecting AgentPlatform to invoke agents directly.

```java
@ShellComponent
public record SupportAgentShellCommands(
        AgentPlatform agentPlatform
) {

    @ShellMethod("Get bank support for a customer query")
    public String bankSupport(
            @ShellOption(value = "id", help = "customer id", defaultValue = "123") Long id,
            @ShellOption(value = "query", help = "customer query", defaultValue = "What's my balance, including pending amounts?") String query
    ) {
        var supportInput = new SupportInput(id, query);
        System.out.println("Support input: " + supportInput);
        var invocation = AgentInvocation
                .builder(agentPlatform)
                .options(ProcessOptions.builder().verbosity(v -> v.showPrompts(true)).build())
                .build(SupportOutput.class);
        var result = invocation.invoke(supportInput);
        return result.toString();
    }
}
```

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

### Test component with Mockito

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Verifies prompt generation and interaction with the Ai interface using Mockito mocks.

```java
class InjectedComponentTest {

    @Test
    void testTellJokeAbout() {
        var mockAi = Mockito.mock(Ai.class);
        var mockPromptRunner = Mockito.mock(PromptRunner.class);

        var prompt = "Tell me a joke about frogs";
        // Yep, an LLM came up with this joke.
        var terribleJoke = """
                Why don't frogs ever pay for drinks?
                Because they always have a tadpole in their wallet!
                """;
        when(mockAi.withDefaultLlm()).thenReturn(mockPromptRunner);
        when(mockPromptRunner.generateText(prompt)).thenReturn(terribleJoke);

        var injectedComponent = new InjectedComponent(mockAi);
        var joke = injectedComponent.tellJokeAbout("frogs");

        assertEquals(terribleJoke, joke);
        Mockito.verify(mockAi).withDefaultLlm();
        Mockito.verify(mockPromptRunner).generateText(prompt);
    }

}
```

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

### Create a simple agent with SimpleAgentBuilder

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Uses SimpleAgentBuilder to define an agent that returns a specific object type after executing an AI action.

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

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

### Configure Agent Execution Options

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Set verbosity levels for prompts, responses, and debugging during agent invocation.

```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)
```

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

### Provide Domain Objects as Tools

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Use withToolObject to register domain objects containing @Tool methods, optionally applying filters or custom naming strategies.

```java
context.ai()
    .withDefaultLlm()
    .withToolObject(jokerTool)
    .createObject("Create a UserInput object for fun", UserInput.class);

// Add tool object with filtering and custom naming strategy
context.ai()
    .withDefaultLlm()
    .withToolObject(
        ToolObject(calculatorService)
            .withNamingStrategy { "calc_$it" }
            .withFilter { methodName -> methodName.startsWith("compute") }
    ).createObject("Perform calculations", Result.class);
```

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

### Basic AgentInvocation Usage

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Invokes an agent using a type-safe API, showing both Java and Kotlin syntax for result type handling.

```java
// Simple invocation with explicit result type
var invocation =
    AgentInvocation.create(agentPlatform, TravelPlan.class);

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

```kotlin
// Type-safe invocation with inferred result type
val invocation: AgentInvocation<TravelPlan> =
    AgentInvocation.create(agentPlatform)

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

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

### Injecting AI into a Spring Component

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates using constructor injection to add AI capabilities to a Spring component, allowing for text generation and structured object creation.

```java
package com.embabel.example.injection;

import com.embabel.agent.api.common.OperationContext;
import com.embabel.common.ai.model.LlmOptions;
import org.springframework.stereotype.Component;

/**
 * Demonstrate the simplest use of Embabel's AI capabilities,
 * injecting an AI helper into a Spring component.
 * The jokes will be terrible, but don't blame Embabel, blame the LLM.
 */
@Component
public record InjectedComponent(Ai ai) {

    public record Joke(String leadup, String punchline) {
    }

    public String tellJokeAbout(String topic) {
        return ai
                .withDefaultLlm()
                .generateText("Tell me a joke about " + topic);
    }

    public Joke createJokeObjectAbout(String topic1, String topic2, String voice) {
        return ai
                .withLlm(LlmOptions.withDefaultLlm().withTemperature(.8))
                .createObject("""
                                Tell me a joke about %s and %s.
                                The voice of the joke should be %s.
                                The joke should have a leadup and a punchline.
                                """.formatted(topic1, topic2, voice),
                        Joke.class);
    }

}
```

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

### PromptRunner

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

The PromptRunner interface is the primary mechanism for executing LLM calls, managing tools, and configuring context.

```APIDOC
## PromptRunner

### Description
Interface for running prompts with specific LLMs, hyperparameters, and tool groups.

### Core Methods
- **createObject(String, Class<T>)**: Create a typed object from a prompt.
- **createObjectIfPossible(String, Class<T>)**: Try to create an object, return null on failure.
- **generateText(String)**: Generate simple text response.

### Configuration Methods
- **withToolGroup(String)**: Add tool groups for LLM access.
- **withToolObject(Object)**: Add domain objects with @Tool methods.
- **withPromptContributor(PromptContributor)**: Add context contributors.
- **withLlm(LlmOptions)**: Use specific LLM configuration.
- **withGenerateExamples(Boolean)**: Control example generation.
- **withTemplate(String)**: Use Jinja templates for prompts.
- **withSubagents(Subagent...)**: Enable handoffs to other agents.
- **evaluateCondition(String, String)**: Evaluate boolean condition.
```

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

### Enable Embabel in Spring Boot

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Annotate the main Spring Boot application class with @EnableAgents to initialize the agent framework and configure local model or MCP tool sources.

```java
@SpringBootApplication
@EnableAgents(
    loggingTheme = LoggingThemes.STAR_WARS,
    localModels = { "docker" },
    mcpClients = { "docker" }
)
class MyAgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyAgentApplication.class, args);
    }
}
```

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

### Execute an agent command

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Run a specific task within the agent shell.

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

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

### Configuring Embabel logging themes

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Use the @EnableAgents annotation to set a specific logging theme for the application.

```kotlin
@SpringBootApplication
@ConfigurationPropertiesScan
@EnableAgents(
        loggingTheme = LoggingThemes.STAR_WARS
)
class MyAwesomeApplication {
    public static void main(String[] args) {
        SpringApplication.run(GuideApplication.class, args);
    }
}
```

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

### Register an Agent as a Spring Bean

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Configures an agent as a Spring bean to enable auto-registration within the application context.

```kotlin
@Configuration
class FactCheckerAgentConfiguration {

    @Bean
    fun factChecker(factCheckerProperties: FactCheckerProperties): Agent {
        return factCheckerAgent(
            llms = listOf(
                LlmOptions(AnthropicModels.CLAUDE_35_HAIKU).withTemperature(.3),
                LlmOptions(AnthropicModels.CLAUDE_35_HAIKU).withTemperature(.0),
            ),
            properties = factCheckerProperties,
        )
    }
}
```

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

### Bind Blackboard Items

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Assigns a specific key to a blackboard item using the context object within an action method.

```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;
}
```

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

### Invoke nested agent processes with ActionContext

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Use ActionContext.asSubProcess to execute a sub-process within an action, useful for composing stereotyped processes.

```kotlin
@Action
fun report(
    reportRequest: ReportRequest,
    context: ActionContext,
): ScoredResult<Report, SimpleFeedback> = context.asSubProcess(
    // Will create an agent sub process with strong typing
    EvaluatorOptimizer.generateUntilAcceptable(
        maxIterations = 5,
        generator = {
            it.promptRunner().withToolGroup(CoreToolGroups.WEB).create(
                """
        Given the topic, generate a detailed report in ${reportRequest.words} words.

        # Topic
        ${reportRequest.topic}

        # Feedback
        ${it.input ?: "No feedback provided"}
                """.trimIndent()
            )
        },
        evaluator = {
            it.promptRunner().withToolGroup(CoreToolGroups.WEB).create(
                """
        Given the topic and word count, evaluate the report and provide feedback
        Feedback must be a score between 0 and 1, where 1 is perfect.

        # Report
        ${it.input.report}

        # Report request:

        ${reportRequest.topic}
        Word count: ${reportRequest.words}
        """.trimIndent()
            )
        },
    ))
```

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

### LlmOptions

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

The LlmOptions class is used to configure LLM hyperparameters such as model selection, temperature, and sampling parameters.

```APIDOC
## LlmOptions

### Description
Specifies which LLM to use and its hyperparameters using a fluent API.

### Methods
- **withModel(String)**: Specify the model name.
- **withTemperature(Double)**: Set creativity/randomness (0.0-1.0).
- **withTopP(Double)**: Set nucleus sampling parameter.
- **withTopK(Integer)**: Set top-K sampling parameter.
- **withPersona(String)**: Add a system message persona.
```

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

### Define component with injected Ai

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Demonstrates a Spring component using direct injection of the Ai interface to generate text.

```java
@Component
public record InjectedComponent(Ai ai) {

    public record Joke(String leadup, String punchline) {
    }

    public String tellJokeAbout(String topic) {
        return ai
                .withDefaultLlm()
                .generateText("Tell me a joke about " + topic);
    }
}
```

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

### Define an Embabel support agent

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Equivalent implementation in Java using Embabel's @Agent and @Tool annotations with Spring integration.

```java
// From embabel-agent-examples/examples-java/src/main/java/com/embabel/example/pydantic/banksupport/SupportAgent.java

record Customer(Long id, String name, float balance, float pendingAmount) {

    @Tool(description = "Find the balance of a customer by id")
    float balance(boolean includePending) {
        return includePending ? balance + pendingAmount : balance;
    }
}

record SupportInput(
    @JsonPropertyDescription("Customer ID") Long customerId,
    @JsonPropertyDescription("Query from the customer") String query) {
}

record SupportOutput(
    @JsonPropertyDescription("Advice returned to the customer") String advice,
    @JsonPropertyDescription("Whether to block their card or not") boolean blockCard,
    @JsonPropertyDescription("Risk level of query") int risk) {
}

@Agent(description = "Customer support agent")
record SupportAgent(CustomerRepository customerRepository) {

    @AchievesGoal(description = "Help bank customer with their query")
    @Action
    SupportOutput supportCustomer(SupportInput supportInput, OperationContext context) {
        var customer = customerRepository.findById(supportInput.customerId());
        if (customer == null) {
            return new SupportOutput("Customer not found with this id", false, 0);
        }
        return context.ai()
            .withLlm(OpenAiModels.GPT_41_MINI)
            .withToolObject(customer)
            .createObject(
                """
                You are a support agent in our bank, give the
                customer support and judge the risk level of their query.
                In some cases, you may need to block their card. In this case, explain why.
                Reply using the customer's name, "%s".
                Currencies are in $.

                Their query: [%s]
                """.formatted(customer.name(), supportInput.query()),
                SupportOutput.class);
    }
}
```

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

### Registering a custom OpenAI-compatible LLM

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Extend OpenAiCompatibleModelFactory to define custom LLM beans in a Spring configuration class.

```kotlin
@Configuration
class CustomOpenAiCompatibleModels(
    @Value("${MY_BASE_URL:#{null}}")
    baseUrl: String?,
    @Value("${MY_API_KEY}")
    apiKey: String,
    observationRegistry: ObservationRegistry,
) : OpenAiCompatibleModelFactory(baseUrl = baseUrl, apiKey = apiKey, observationRegistry = observationRegistry) {

    @Bean
    fun myGreatModel(): Llm {
        // Call superclass method
        return openAiCompatibleLlm(
            model = "my-great-model",
            provider = "me",
            knowledgeCutoffDate = LocalDate.of(2025, 1, 1),
            pricingModel = PerTokenPricingModel(
                usdPer1mInputTokens = .40,
                usdPer1mOutputTokens = 1.6,
            )
        )
    }
}
```

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

### Configuring logging levels in application.properties

Source: https://docs.embabel.com/embabel-agent/guide/0.1.3

Set specific package logging levels using standard Spring Boot configuration properties.

```properties
logging.level.com.embabel.agent.a2a=DEBUG
```
Tokens:
Raw