Class DefaultAgenticScope

java.lang.Object
dev.langchain4j.agentic.scope.DefaultAgenticScope
All Implemented Interfaces:
AgenticScope, LangChain4jManaged
public class DefaultAgenticScope extends Object implements AgenticScope

  • Method Details

    • ephemeralAgenticScope

      public static DefaultAgenticScope ephemeralAgenticScope()

    • memoryId

      public Object memoryId()
      Description copied from interface: AgenticScope
      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.
      Specified by:
      memoryId in interface AgenticScope
      Returns:
      the memory identifier

    • writeState

      public void writeState(String key, Object value)
      Description copied from interface: AgenticScope
      Writes a value into the shared state under the given key. If the value is null, the key is removed from the state.
      Specified by:
      writeState in interface AgenticScope
      Parameters:
      key - the state key
      value - the value to store, or null to remove the key

    • writeState

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

    • writeStates

      public void writeStates(Map<String,Object> newState)
      Description copied from interface: AgenticScope
      Writes multiple key-value pairs into the shared state at once.
      Specified by:
      writeStates in interface AgenticScope
      Parameters:
      newState - a map of key-value pairs to store

    • hasState

      public boolean hasState(String key)
      Description copied from interface: AgenticScope
      Checks whether the shared state contains a non-blank value for the given key.
      Specified by:
      hasState in interface AgenticScope
      Parameters:
      key - the state key
      Returns:
      true if the key exists and its value is non-null (and non-blank for strings)

    • hasState

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

    • readState

      public Object readState(String key)
      Description copied from interface: AgenticScope
      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.
      Specified by:
      readState in interface AgenticScope
      Parameters:
      key - the state key
      Returns:
      the value, or null if the key is not present

    • readState

      public <T> T readState(String key, T defaultValue)
      Description copied from interface: AgenticScope
      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.
      Specified by:
      readState in interface AgenticScope
      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

      public <T> T readState(Class<? extends TypedKey<T>> key)
      Description copied from interface: AgenticScope
      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.
      Specified by:
      readState in interface AgenticScope
      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

      public Map<String,Object> state()
      Description copied from interface: AgenticScope
      Returns a live view of the entire shared state map. Modifications to this map are reflected in the scope's state.
      Specified by:
      state in interface AgenticScope
      Returns:
      the mutable state map

    • getOrCreateAgent

      public <T> T getOrCreateAgent(String agentId, Function<DefaultAgenticScope, T> agentFactory)

    • registerAgentInvocation

      public void registerAgentInvocation(AgentInvocation agentInvocation, Object agent)

    • rootCallStarted

      public void rootCallStarted(AgenticScopeRegistry registry)

    • rootCallEnded

      public void rootCallEnded(AgenticScopeRegistry registry, AgentListener agentListener)

    • context

      public List<DefaultAgenticScope.AgentMessage> context()

    • contextAsConversation

      public String contextAsConversation(Object... agents)
      Description copied from interface: AgenticScope
      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.
      Specified by:
      contextAsConversation in interface AgenticScope
      Parameters:
      agents - the agent instances to include; if empty, all agents are included
      Returns:
      the conversation context as a formatted string

    • contextAsConversation

      public String contextAsConversation(String... agentNames)
      Description copied from interface: AgenticScope
      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.
      Specified by:
      contextAsConversation in interface AgenticScope
      Parameters:
      agentNames - the names of the agents to include; if empty, all agents are included
      Returns:
      the conversation context as a formatted string

    • agentInvocations

      public List<AgentInvocation> agentInvocations()
      Description copied from interface: AgenticScope
      Returns all agent invocations recorded in this scope, in execution order.
      Specified by:
      agentInvocations in interface AgenticScope
      Returns:
      an unmodifiable list of all agent invocations

    • agentInvocations

      public List<AgentInvocation> agentInvocations(String agentName)
      Description copied from interface: AgenticScope
      Returns all agent invocations for the agent with the given name.
      Specified by:
      agentInvocations in interface AgenticScope
      Parameters:
      agentName - the name of the agent
      Returns:
      a list of invocations matching the agent name

    • agentInvocations

      public List<AgentInvocation> agentInvocations(Class<?> agentType)
      Description copied from interface: AgenticScope
      Returns all agent invocations for agents of the given type.
      Specified by:
      agentInvocations in interface AgenticScope
      Parameters:
      agentType - the class of the agent
      Returns:
      a list of invocations matching the agent type

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • withErrorHandler

      public DefaultAgenticScope withErrorHandler(Function<ErrorContext, ErrorRecoveryResult> errorHandler)

    • handleError

      public ErrorRecoveryResult handleError(String agentName, AgentInvocationException exception)

    • checkpoint

      public void checkpoint(AgenticScopeRegistry registry)
      Checkpoints the current state of this scope by persisting it to the store. This is a no-op for non-persistent scopes. For persistent scopes, it acquires the write lock and flushes the current state to the store.
      Parameters:
      registry - the registry managing this scope's persistence

    • completePendingResponse

      public boolean completePendingResponse(String responseId, Object value)
      Description copied from interface: AgenticScope
      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.
      Specified by:
      completePendingResponse in interface AgenticScope
      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

      public Set<String> pendingResponseIds()
      Description copied from interface: AgenticScope
      Returns the identifiers of all PendingResponse instances stored in this scope's state that have not yet been completed.
      Specified by:
      pendingResponseIds in interface AgenticScope
      Returns:
      a set of pending response identifiers