Package com.embabel.agent.api.common

Interface PromptRunner

  • All Implemented Interfaces:
    com.embabel.agent.api.common.PromptRunnerOperations , com.embabel.agent.api.tool.agentic.ToolChaining , com.embabel.agent.core.ToolGroupConsumer , com.embabel.agent.core.support.LlmUse , com.embabel.common.ai.prompt.PromptContributorConsumer 
    
public interface PromptRunner
 implements LlmUse, PromptRunnerOperations, ToolChaining<PromptRunner>

    User code should always use this interface to execute prompts. Typically obtained from an OperationContext or ActionContext parameter, via OperationContext.ai A PromptRunner is immutable once constructed, and has determined LLM and hyperparameters. Use the "with" methods to evolve the state to your desired configuration before executing createObject, generateText or other LLM invocation methods. Thus, a PromptRunner can be reused within an action implementation. A contextual facade to LlmOperations.

    • Constructor Detail

    • Method Detail

      • withImage

         PromptRunner withImage(AgentImage image)

        Add an image that will be included in the final prompt. Images will be combined with the prompt text when operations are executed.

      • withToolGroup

         PromptRunner withToolGroup(String toolGroup)

        Add a tool group to the PromptRunner

        Parameters:
        toolGroup - name of the toolGroup we're requesting
        Returns:

        PromptRunner instance with the added tool group

      • withToolGroups

         PromptRunner withToolGroups(String toolGroups)

        Add tool groups to the PromptRunner by name (varargs version).

        Parameters:
        toolGroups - the tool group names to add

      • withTools

        @Deprecated(message = "Use withToolGroups() instead for tool group names", replaceWith = @ReplaceWith(imports = {}, expression = "withToolGroups(*toolGroups)")) PromptRunner withTools(String toolGroups)

        Add a set of tool groups to the PromptRunner

        Parameters:
        toolGroups - the set of named tool groups to add

      • withTools

         PromptRunner withTools(List<Tool> tools)

        Add multiple framework-agnostic Tools to the prompt runner.

        Parameters:
        tools - the tools to add
        Returns:

        PromptRunner instance with the added tools

      • withTools

         PromptRunner withTools(Tool tool, Tool tools)

        Add multiple framework-agnostic Tools to the prompt runner. Uses required first parameter to avoid ambiguity with withTools for tool group names.

        Parameters:
        tool - the first tool to add (required)
        tools - additional tools to add
        Returns:

        PromptRunner instance with the added tools

      • withToolObject

         PromptRunner withToolObject(Object toolObject)

        Add a tool object to the prompt runner. The tool object should have @Tool annotations.

        Parameters:
        toolObject - the object to add.
        Returns:

        PromptRunner instance with the added tool object

      • withToolObjects

         PromptRunner withToolObjects(Object toolObject, Object toolObjects)

        Add multiple tool objects to the prompt runner. Uses required first parameter to avoid ambiguity.

        Parameters:
        toolObject - the first tool object to add (required)
        toolObjects - additional tool objects to add
        Returns:

        PromptRunner instance with the added tool objects

      • withTool

         abstract PromptRunner withTool(Tool tool)

        Add a framework-agnostic Tool to the prompt runner.

        Parameters:
        tool - the tool to add
        Returns:

        PromptRunner instance with the added tool

      • withFunctionTools

        @Deprecated(message = "Use withTools(tool, *tools) instead", replaceWith = @ReplaceWith(imports = {}, expression = "withTools(tools[0], *tools.drop(1).toTypedArray())")) PromptRunner withFunctionTools(Tool tools)

        Add multiple framework-agnostic Tools to the prompt runner (varargs version).

        Parameters:
        tools - the tools to add
        Returns:

        PromptRunner instance with the added tools

      • withPromptContributor

         PromptRunner withPromptContributor(PromptContributor promptContributor)

        Add a prompt contributor that can add to the prompt. Facilitates reuse of prompt elements.

        Returns:

        PromptRunner instance with the added PromptContributor

      • withGenerateExamples

         abstract PromptRunner withGenerateExamples(Boolean generateExamples)

        Set whether to generate examples of the output in the prompt on a per-PromptRunner basis. This overrides platform defaults. Note that adding individual examples with Creating.withExample will always override this.

      • withPropertyFilter

        @Deprecated(message = "Use creating().withPropertyFilter() instead", replaceWith = @ReplaceWith(imports = {}, expression = "creating(outputClass).withPropertyFilter(filter)")) abstract PromptRunner withPropertyFilter(Predicate<String> filter)

        Adds a filter that determines which properties are to be included when creating an object.

        Note that each predicate is applied in addition to previously registered predicates.

        Parameters:
        filter - the property predicate to be added

      • withValidation

        @Deprecated(message = "Use creating().withValidation() instead", replaceWith = @ReplaceWith(imports = {}, expression = "creating(outputClass).withValidation(validation)")) abstract PromptRunner withValidation(Boolean validation)

        Set whether to validate created objects.

        Parameters:
        validation - true to validate created objects; false otherwise.

      • withGuardRails

         abstract PromptRunner withGuardRails(GuardRail guards)

        Add guardrail instances to this PromptRunner (additive).

        Parameters:
        guards - the guardrail instances to add
        Returns:

        PromptRunner instance with additional guardrails configured

      • creating

         abstract <T extends Any> PromptRunner.Creating<T> creating(Class<T> outputClass)

        Returns a mode for creating strongly-typed objects.

        Parameters:
        outputClass - the class of objects to create
        Returns:

        creating mode supporting examples, property filtering, and validation

      • rendering

         abstract PromptRunner.Rendering rendering(String templateName)

        Returns Rendering for rendering the specified template.

        Parameters:
        templateName - the name of the template to render
        Returns:

        rendering mode for creating objects and generating text from templates

      • supportsStreaming

         Boolean supportsStreaming()

        Check if true reactive streaming is supported by the underlying LLM model. Always check this before calling stream() to avoid exceptions.

        Returns:

        true if real-time streaming is supported, false if streaming is not available

      • stream

        @Deprecated(message = "Use streaming() instead", replaceWith = @ReplaceWith(imports = {}, expression = "streaming()")) PromptRunner.StreamingCapability stream()

        Create streaming operations for this prompt runner configuration.

        This follows an explicit failure policy - if streaming is not supported by the underlying LLM implementation, this method will throw an exception rather than providing fallback behavior. Always check supportsStreaming() first for safe usage.

        Returns:

        StreamingCapability instance providing access to streaming operations

      • supportsThinking

         Boolean supportsThinking()

        Check if thinking extraction capabilities are supported by the underlying implementation.

        Thinking capabilities allow extraction of thinking blocks (like <think>...</think>) from LLM responses and provide access to both the result and the extracted thinking content. Always check this before calling thinking() to avoid exceptions.

        Note: Thinking and streaming capabilities are mutually exclusive.

        Returns:

        true if thinking extraction is supported, false if thinking is not available

      • withThinking

        @Deprecated(message = "Use thinking() instead", replaceWith = @ReplaceWith(imports = {}, expression = "thinking()")) PromptRunner.Thinking withThinking()

        Create a thinking-enhanced version of this prompt runner.

        Returns a PromptRunner where all operations (createObject, generateText, etc.) return ThinkingResponse<T> wrappers that include both results and extracted thinking blocks from the LLM response.

        Always check supportsThinking() first and ensure LlmOptions includes thinking configuration via withLlm(LlmOptions.withThinking(Thinking.withExtraction())).

        Note: Thinking and streaming capabilities are mutually exclusive.

        Returns:

        ThinkingCapability instance providing access to thinking-aware operations