Interface AgenticScope

All Superinterfaces:
LangChain4jManaged
All Known Implementing Classes:
DefaultAgenticScope
public interface AgenticScope extends LangChain4jManaged
The AgenticScope class represents a common environment where agents belonging to the same agentic system can share their state. It maintains the state of the computation, tracks agent invocations, and provides methods to allow agents to interact with the shared state.

Agents can register their calls, and the context of interactions is stored for later retrieval. The class also provides methods to read and write state, manage agent invocations, and retrieve the context as a conversation.

  • Method Details

    • memoryId

      Object memoryId()
      Returns the unique memory identifier for this scope. This ID is used to associate the scope with a specific conversation or session, and to look up persisted scopes from a store.
      Returns:
      the memory identifier

    • writeState

      void writeState(String key, Object value)
      Writes a value into the shared state under the given key. If the value is null, the key is removed from the state.
      Parameters:
      key - the state key
      value - the value to store, or null to remove the key

    • writeState

      <T> void writeState(Class<? extends TypedKey<T>> key, T value)
      Writes a value into the shared state using a strongly typed key. The key's name is derived from the TypedKey class.
      Type Parameters:
      T - the type of the value
      Parameters:
      key - the typed key class
      value - the value to store

    • writeStates

      void writeStates(Map<String,Object> newState)
      Writes multiple key-value pairs into the shared state at once.
      Parameters:
      newState - a map of key-value pairs to store

    • hasState

      boolean hasState(String key)
      Checks whether the shared state contains a non-blank value for the given key.
      Parameters:
      key - the state key
      Returns:
      true if the key exists and its value is non-null (and non-blank for strings)

    • hasState

      boolean hasState(Class<? extends TypedKey<?>> key)
      Checks whether the shared state contains a non-blank value for the given typed key.
      Parameters:
      key - the typed key class
      Returns:
      true if the key exists and its value is non-null (and non-blank for strings)

    • readState

      Object readState(String key)
      Reads the value associated with the given key from the shared state. If the value is a DelayedResponse, this method blocks until the response is available.
      Parameters:
      key - the state key
      Returns:
      the value, or null if the key is not present

    • readState

      <T> T readState(String key, T defaultValue)
      Reads the value associated with the given key from the shared state, returning a default value if the key is not present. If the value is a DelayedResponse, this method blocks until the response is available.
      Type Parameters:
      T - the type of the value
      Parameters:
      key - the state key
      defaultValue - the value to return if the key is not present
      Returns:
      the value, or defaultValue if the key is not present

    • readState

      <T> T readState(Class<? extends TypedKey<T>> key)
      Reads the value associated with the given typed key from the shared state. The key's name and default value are derived from the TypedKey class. If the value is a DelayedResponse, this method blocks until the response is available.
      Type Parameters:
      T - the type of the value
      Parameters:
      key - the typed key class
      Returns:
      the value, or the key's default value if not present

    • state

      Map<String,Object> state()
      Returns a live view of the entire shared state map. Modifications to this map are reflected in the scope's state.
      Returns:
      the mutable state map

    • contextAsConversation

      String contextAsConversation(String... agentNames)
      Returns the conversation context as a human-readable string, optionally filtered by agent names. Each entry shows the user message and the agent's response.
      Parameters:
      agentNames - the names of the agents to include; if empty, all agents are included
      Returns:
      the conversation context as a formatted string

    • contextAsConversation

      String contextAsConversation(Object... agents)
      Returns the conversation context as a human-readable string, optionally filtered by agent instances. Each entry shows the user message and the agent's response.
      Parameters:
      agents - the agent instances to include; if empty, all agents are included
      Returns:
      the conversation context as a formatted string

    • agentInvocations

      List<AgentInvocation> agentInvocations()
      Returns all agent invocations recorded in this scope, in execution order.
      Returns:
      an unmodifiable list of all agent invocations

    • agentInvocations

      List<AgentInvocation> agentInvocations(String agentName)
      Returns all agent invocations for the agent with the given name.
      Parameters:
      agentName - the name of the agent
      Returns:
      a list of invocations matching the agent name

    • agentInvocations

      List<AgentInvocation> agentInvocations(Class<?> agentType)
      Returns all agent invocations for agents of the given type.
      Parameters:
      agentType - the class of the agent
      Returns:
      a list of invocations matching the agent type

    • completePendingResponse

      default boolean completePendingResponse(String responseId, Object value)
      Completes a PendingResponse stored in this scope's state. This is typically called by an external system (e.g., a REST endpoint) to provide a human's response after a process restart or when using a polling/event-driven model.
      Parameters:
      responseId - the unique identifier of the pending response
      value - the value to complete the response with
      Returns:
      true if a matching pending response was found and completed

    • pendingResponseIds

      default Set<String> pendingResponseIds()
      Returns the identifiers of all PendingResponse instances stored in this scope's state that have not yet been completed.
      Returns:
      a set of pending response identifiers