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

    • writeExecutionContext

      void writeExecutionContext(String key, Object context)
      Stores non-serializable execution context in this scope, keyed by name.

      This allows custom Planner implementations to store runtime objects that are needed during execution but should not be persisted. The execution context is stored in a transient map and will not be serialized.

      This is distinct from writeState(String, Object), which is for serializable agent interaction data that forms part of the conversation state.

      Parameters:
      key - the key to use for this context (must not be null)
      context - the execution context instance to store (must not be null)
      Throws:
      IllegalArgumentException - if key or context is null

    • writeExecutionContext

      default void writeExecutionContext(Class<?> type, Object context)
      Stores non-serializable execution context in this scope, using the class name as the key.

      This is a convenience method that delegates to writeExecutionContext(String, Object) using the fully qualified class name as the key.

      Parameters:
      type - the class type to use as the key for this context
      context - the execution context instance to store
      Throws:
      IllegalArgumentException - if context is null

    • executionContext

      Object executionContext(String key)
      Retrieves non-serializable execution context from this scope by key.

      Returns execution context previously stored via writeExecutionContext(String, Object).

      Parameters:
      key - the key used to store the execution context
      Returns:
      the execution context instance previously stored for this key, or null if none exists

    • executionContextAs

      <T> T executionContextAs(String key, Class<T> type)
      Retrieves non-serializable execution context from this scope by key with type-safe casting.

      Returns execution context previously stored via writeExecutionContext(String, Object).

      Type Parameters:
      T - the type of the execution context
      Parameters:
      key - the key used to store the execution context
      type - the expected type of the execution context (for type-safe casting)
      Returns:
      the execution context instance previously stored for this key, or null if none exists
      Throws:
      ClassCastException - if the stored context cannot be cast to the expected type

    • executionContextAs

      default <T> T executionContextAs(Class<T> type)
      Retrieves non-serializable execution context from this scope by type.

      This is a convenience method that delegates to executionContextAs(String, Class) using the fully qualified class name as the key.

      Type Parameters:
      T - the type of the execution context
      Parameters:
      type - the class type used as the key for the execution context
      Returns:
      the execution context instance previously stored for this type, or null if none exists