Module jakarta.ai.agent
Package jakarta.ai.agent

Interface LargeLanguageModel

public interface LargeLanguageModel
Minimal facade for Large Language Model (LLM) operations.

Intended to be injected via CDI into agents. Provides a unified interface for parameterized querying of LLMs with support for type conversion of parameters and results.

Implementations must use Jakarta JSON Binding for serialization of structured prompt parameters and deserialization of typed responses. This ensures consistent, portable behavior across implementations.

For the varargs query methods, supplied parameters are positional. The exact token {} in the prompt acts as a placeholder marker, similar to well-known logger APIs. Implementations must substitute placeholders in declaration order using the Jakarta JSON Binding serialization of the corresponding parameter. When the prompt contains one or more {} placeholders, the number of supplied parameters must exactly match the number of placeholders. When the prompt contains no placeholder, at most one supplied parameter may be made available to the model as structured context. Only the exact token {} is treated as a placeholder; other brace usage remains literal prompt text. A single supplied parameter is therefore valid either as the value for one {} placeholder or as structured context when the prompt contains no placeholder. 


 llm.query("Classify this event: {}", event);
 llm.query("Classify this event", event);

Implementations must maintain conversational state for the current workflow context across query calls. For WorkflowScoped agents, that conversational state is bound to the workflow context and must end when the workflow context ends. For @ApplicationScoped agents, conversational state must remain isolated per workflow context and must not leak across concurrent invocations.

Implementations must be thread-safe within a single workflow context.

Implementations will delegate to external LLM APIs or services.

In the initial release, implementations are free to support whichever LLM libraries and APIs they choose. Configuration mechanisms (if any) are implementation-specific. Future releases will provide standardized provider selection and some common LLM configuration, allowing developers to switch between different LLM implementations, and rely on very common configurable LLM features in a standardized way. Common examples may include temperature or maximum output tokens. This is very similar to how Jakarta Persistence works with multiple providers and a common set of configuration properties.

Since:
1.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    query(String prompt)
    Sends a prompt to the model and returns a String response.
    <T> T
    query(String prompt, Class<T> resultType)
    Sends a prompt to the model and returns a response of the specified type.
    <T> T
    query(String prompt, Class<T> resultType, Object... parameters)
    Sends a prompt template and a variable number of parameters to the model, returning a response of the specified type.
    String
    query(String prompt, Object... parameters)
    Sends a prompt template and a variable number of parameters to the model, returning a String response.
    <T> T
    unwrap(Class<T> implClass)
    Unwraps the underlying LLM implementation.

  • Method Details

    • query

      String query(String prompt)
      Sends a prompt to the model and returns a String response.

      This is the simplest form of LLM interaction, suitable for plain text prompts and responses.

      Parameters:
      prompt - The input prompt or question.
      Returns:
      The model's response as a String.
      Throws:
      IllegalArgumentException - if the prompt is null or invalid.
      LLMException - if the LLM service encounters an error during processing.

    • query

      <T> T query(String prompt, Class<T> resultType)
      Sends a prompt to the model and returns a response of the specified type.

      The LLM response (expected to be JSON) is deserialized to the requested type using Jakarta JSON Binding.

      Type Parameters:
      T - The type of the result.
      Parameters:
      prompt - The prompt or query.
      resultType - The expected result type.
      Returns:
      The model's response converted to the specified type.
      Throws:
      IllegalArgumentException - if the prompt or resultType is null.
      LLMException - if the LLM service encounters an error during processing, or if the response cannot be deserialized to the requested type.

    • query

      String query(String prompt, Object... parameters)
      Sends a prompt template and a variable number of parameters to the model, returning a String response.

      Parameters are serialized to JSON using Jakarta JSON Binding. The exact token {} in the prompt indicates a positional substitution point. Implementations must substitute parameters in declaration order, similar to well-known logger APIs. When the prompt contains one or more {} placeholders, the number of supplied parameters must exactly match the number of placeholders. When the prompt contains no placeholder, at most one supplied parameter may still be sent to the LLM as structured context.

      Parameters:
      prompt - The prompt or prompt template.
      parameters - The positional parameters, or a single structured context object when the prompt contains no placeholder.
      Returns:
      The model's response as a String.
      Throws:
      IllegalArgumentException - if the prompt is null, if the number of supplied parameters does not match the number of {} placeholders, except that a prompt with no placeholder may accept at most one supplied parameter, or if a parameter cannot be serialized to JSON.
      LLMException - if the LLM service encounters an error during processing.

    • query

      <T> T query(String prompt, Class<T> resultType, Object... parameters)
      Sends a prompt template and a variable number of parameters to the model, returning a response of the specified type.

      Parameters are serialized to JSON using Jakarta JSON Binding. The exact token {} in the prompt indicates a positional substitution point. Implementations must substitute parameters in declaration order, similar to well-known logger APIs. When the prompt contains one or more {} placeholders, the number of supplied parameters must exactly match the number of placeholders. When the prompt contains no placeholder, at most one supplied parameter may still be sent to the LLM as structured context. The LLM response (expected to be JSON) is deserialized to the requested type using Jakarta JSON Binding.

      Type Parameters:
      T - The type of the result.
      Parameters:
      prompt - The prompt or prompt template.
      resultType - The expected result type.
      parameters - The positional parameters, or a single structured context object when the prompt contains no placeholder.
      Returns:
      The model's response converted to the specified type.
      Throws:
      IllegalArgumentException - if the prompt or resultType is null, if the number of supplied parameters does not match the number of {} placeholders, except that a prompt with no placeholder may accept at most one supplied parameter, or if a parameter cannot be converted.
      LLMException - if the LLM service encounters an error during processing, or if the response cannot be deserialized to the requested type.

    • unwrap

      <T> T unwrap(Class<T> implClass)
      Unwraps the underlying LLM implementation.

      This allows access to vendor-specific APIs or advanced features not exposed by the facade. Similar to Jakarta Persistence's EntityManager.unwrap() pattern.

      Type Parameters:
      T - The type of the underlying implementation.
      Parameters:
      implClass - The class of the underlying implementation to unwrap to.
      Returns:
      The underlying implementation instance.
      Throws:
      IllegalArgumentException - if the implementation cannot be unwrapped to the requested type.