Interface InvocationContext

All Known Implementing Classes:
DefaultInvocationContext

public interface InvocationContext
Represents the context of a single AI Service invocation. A new instance is created each time an AI Service method is invoked, and it exists until the end of the AI Service invocation, potentially spanning multiple calls to the ChatModel.
Since:
1.6.0
  • Method Details

    • invocationId

      UUID invocationId()
      Unique identifier for an entire AI Service invocation. AI Services created with AiServices treat each subscription to a publisher returned by an AI Service method as a separate invocation, with its own identifier.
    • parentInvocationId

      @Experimental default UUID parentInvocationId()
      The invocationId() of the parent invocation: the AI Service invocation whose own work started this invocation. This is the case when one of these parts of an AI Service calls another AI Service:
      • a tool, a tool error handler or the strategy for hallucinated tool names
      • a tool provider
      • an input or output guardrail
      • a component of the retrieval augmentor (for example a query transformer or a content retriever)
      • the system or user message provider, or the system message transformer
      • the chat memory (including its ChatMemoryStore) or the chat memory provider
      • the moderation model
      • the chatRequestTransformer
      • the chat model itself (for example your own ChatModel implementation)

      It is null when the AI Service is called from your own code (for example from a handler of a TokenStream or from a listener, also from those of an AI Service that itself has a parent), when there is no parent, or when this InvocationContext implementation does not track it.

      The parent is also known when LangChain4j itself runs that part on another thread (for example tools executed concurrently, or a blocking content retriever offloaded to an executor). But if your own code in that part hands the call to another thread (for example with CompletableFuture.supplyAsync(..., executor)), it is null. In rare cases, when futures are shared between invocations, it can even name another invocation. So treat it as best effort.

      It is filled by the AI Service implementation that LangChain4j provides. Frameworks that replace that implementation (for example through AiServicesFactory) return null until they add support for it, also for AI Services they create through AiServices.builder(...).

      It is set when the AI Service method is called: later runs of the same TokenStream keep it.

      Agents run by an agentic workflow (sequence, parallel, loop, conditional) or by a supervisor currently have no parent. An agent called from a tool of another agent has one.

      Returns:
      the id of the parent invocation, or null if there is none or it is not known
      Since:
      1.23.0
    • interfaceName

      String interfaceName()
      The fully-qualified name of the AI Service interface where the invocation was initiated from
      See Also:
    • methodName

      String methodName()
      The method name on interfaceName() where the invocation was initiated from
    • methodReturnType

      @Experimental default Type methodReturnType()
      The declared return type of the AI Service method, including its type arguments (for example List<String> or TokenStream).

      Frameworks that create the context with their own AI Service implementation return null until they add support for it.

      Returns:
      the return type of the AI Service method, or null if it is not known
      Since:
      1.24.0
    • methodArguments

      List<Object> methodArguments()
      The arguments passed into the AI Service method
    • userMessage

      default UserMessage userMessage()
      The UserMessage to be sent to the LLM. This is the message after all transformations (RAG augmentation, content injection, input guardrails, output format instructions).
      Since:
      1.13.0
    • originalUserMessage

      default UserMessage originalUserMessage()
      The UserMessage created from the AI Service method and its prompt template, before any transformation (RAG augmentation, content injection, input guardrails, output format instructions). It is what the user asked, without the retrieved content, for example to decide which tools or models are relevant to the question.
      Since:
      1.21.0
    • chatMemoryId

      Object chatMemoryId()
      The chat memory id parameter of the method
    • defaultRequestParameters

      default ChatRequestParameters defaultRequestParameters()
      Returns the default ChatRequestParameters of the chat model configured on the AI service.
      Since:
      1.16.0
    • modelProvider

      default ModelProvider modelProvider()
      Returns the ModelProvider of the chat model configured on the AI service.
      Since:
      1.16.0
    • invocationParameters

      InvocationParameters invocationParameters()
      The invocation parameters
    • managedParameters

      default Map<Class<? extends LangChain4jManaged>, LangChain4jManaged> managedParameters()
      LangChain4j managed parameters
      Since:
      1.8.0
    • timestamp

      Instant timestamp()
      Retrieves the point in time when the invocation occurred.
    • toBuilder

      default InvocationContext.Builder toBuilder()
      Converts the current instance of DefaultInvocationContext into a InvocationContext.Builder, pre-populated with the current values of the instance.

      When this is a DefaultInvocationContext, a copy built with the same invocationId() shares whether the invocation has already reported its end (see InvocationEnd).

    • builder

      static InvocationContext.Builder builder()
      Creates a new instance of the Builder class for constructing instances of DefaultInvocationContext.