Package com.alibaba.cloud.ai.graph.agent

Class Agent

java.lang.Object
com.alibaba.cloud.ai.graph.agent.Agent
Direct Known Subclasses:
BaseAgent, FlowAgent
public abstract class Agent extends Object
Abstract base class for all agents in the graph system. Contains common properties and methods shared by different agent implementations.

  • Field Details

    • name

      protected String name
      The agent's name. Must be a unique identifier within the graph.

    • description

      protected String description
      One line description about the agent's capability. The system can use this for decision-making when delegating control to different agents.

    • compileConfig

      protected CompileConfig compileConfig

    • compiledGraph

      protected volatile CompiledGraph compiledGraph

    • graph

      protected volatile StateGraph graph

    • executor

      protected Executor executor

  • Constructor Details

    • Agent

      protected Agent(String name, String description)
      Protected constructor for initializing all base agent properties.
      Parameters:
      name - the unique name of the agent
      description - the description of the agent's capability

    • Agent

      protected Agent()
      Default protected constructor for subclasses that need to initialize properties differently.

  • Method Details

    • name

      public String name()
      Gets the agent's unique name.
      Returns:
      the unique name of the agent.

    • description

      public String description()
      Gets the one-line description of the agent's capability.
      Returns:
      the description of the agent.

    • getGraph

      public StateGraph getGraph()

    • getAndCompileGraph

      public CompiledGraph getAndCompileGraph()

    • schedule

      public ScheduledAgentTask schedule(org.springframework.scheduling.Trigger trigger, Map<String,Object> input) throws GraphStateException, GraphRunnerException
      Schedule the agent task with trigger.
      Parameters:
      trigger - the schedule configuration
      input - the agent input
      Returns:
      a ScheduledAgentTask instance for managing the scheduled task
      Throws:
      GraphStateException
      GraphRunnerException

    • schedule

      public ScheduledAgentTask schedule(ScheduleConfig scheduleConfig) throws GraphStateException
      Schedule the agent task with trigger.
      Parameters:
      scheduleConfig - the schedule configuration
      Returns:
      a ScheduledAgentTask instance for managing the scheduled task
      Throws:
      GraphStateException

    • getCurrentState

      public StateSnapshot getCurrentState(RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invoke

      public Optional<OverAllState> invoke(String message) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invoke

      public Optional<OverAllState> invoke(String message, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invoke

      public Optional<OverAllState> invoke(org.springframework.ai.chat.messages.UserMessage message) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invoke

      public Optional<OverAllState> invoke(org.springframework.ai.chat.messages.UserMessage message, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invoke

      public Optional<OverAllState> invoke(List<org.springframework.ai.chat.messages.Message> messages) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invoke

      public Optional<OverAllState> invoke(List<org.springframework.ai.chat.messages.Message> messages, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invoke

      public Optional<OverAllState> invoke(Map<String,Object> inputs) throws GraphRunnerException
      Invokes the agent with the given inputs map.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      Returns:
      the resulting overall state, or empty if none
      Throws:
      GraphRunnerException - if the graph execution fails

    • invoke

      public Optional<OverAllState> invoke(Map<String,Object> inputs, RunnableConfig config) throws GraphRunnerException
      Invokes the agent with the given inputs map and runtime config.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      config - runtime configuration controlling execution behavior
      Returns:
      the resulting overall state, or empty if none
      Throws:
      GraphRunnerException - if the graph execution fails

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(String message) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(String message, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(org.springframework.ai.chat.messages.UserMessage message) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(org.springframework.ai.chat.messages.UserMessage message, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(List<org.springframework.ai.chat.messages.Message> messages) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(List<org.springframework.ai.chat.messages.Message> messages, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(Map<String,Object> inputs) throws GraphRunnerException
      Invokes the agent with the given inputs map and returns the node output.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      Returns:
      the node output, or empty if none
      Throws:
      GraphRunnerException - if the graph execution fails

    • invokeAndGetOutput

      public Optional<NodeOutput> invokeAndGetOutput(Map<String,Object> inputs, RunnableConfig config) throws GraphRunnerException
      Invokes the agent with the given inputs map and runtime config, returns the node output.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      config - runtime configuration controlling execution behavior
      Returns:
      the node output, or empty if none
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(String message) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using a plain text input.

      This is a convenience API built on top of stream(...) that extracts and emits Message instances directly instead of low-level NodeOutput objects. It is intended for use cases that only care about the generated messages and do not require access to graph orchestration or node execution details.

      Parameters:
      message - the input message as plain text
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(String message, RunnableConfig config) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using a plain text input and a custom RunnableConfig.
      Parameters:
      message - the input message as plain text
      config - runtime configuration controlling execution behavior
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(org.springframework.ai.chat.messages.UserMessage message) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using a UserMessage as input.
      Parameters:
      message - the user message input
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(org.springframework.ai.chat.messages.UserMessage message, RunnableConfig config) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using a UserMessage as input and a custom RunnableConfig.
      Parameters:
      message - the user message input
      config - runtime configuration controlling execution behavior
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(List<org.springframework.ai.chat.messages.Message> messages) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using a list of input Message instances.
      Parameters:
      messages - the input messages
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(List<org.springframework.ai.chat.messages.Message> messages, RunnableConfig config) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using a list of input Message instances and a custom RunnableConfig.
      Parameters:
      messages - the input messages
      config - runtime configuration controlling execution behavior
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(Map<String,Object> inputs) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using an inputs map.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • streamMessages

      public reactor.core.publisher.Flux<org.springframework.ai.chat.messages.Message> streamMessages(Map<String,Object> inputs, RunnableConfig config) throws GraphRunnerException
      Streams the execution result as a Flux of Message objects using an inputs map and a custom RunnableConfig.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      config - runtime configuration controlling execution behavior
      Returns:
      a Flux emitting Message objects as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(String message) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(String message, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(org.springframework.ai.chat.messages.UserMessage message) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(org.springframework.ai.chat.messages.UserMessage message, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(List<org.springframework.ai.chat.messages.Message> messages) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(List<org.springframework.ai.chat.messages.Message> messages, RunnableConfig config) throws GraphRunnerException
      Throws:
      GraphRunnerException

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(Map<String,Object> inputs) throws GraphRunnerException
      Streams the graph execution with the given inputs map.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      Returns:
      a Flux emitting NodeOutput as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • stream

      public reactor.core.publisher.Flux<NodeOutput> stream(Map<String,Object> inputs, RunnableConfig config) throws GraphRunnerException
      Streams the graph execution with the given inputs map and runtime config.

      When you need to pass additional parameters beyond messages and input, use this overload.

      Reserved keys: messages and input are used as question/input for the agent. Other keys can be arbitrary and are passed as graph state, e.g. for prompt placeholders or any other state values.

      Parameters:
      inputs - the input map (reserved: messages, input; other keys as state)
      config - runtime configuration controlling execution behavior
      Returns:
      a Flux emitting NodeOutput as they are produced
      Throws:
      GraphRunnerException - if the graph execution fails

    • doInvoke

      protected Optional<OverAllState> doInvoke(Map<String,Object> input, RunnableConfig runnableConfig)

    • doInvokeAndGetOutput

      protected Optional<NodeOutput> doInvokeAndGetOutput(Map<String,Object> input, RunnableConfig runnableConfig)

    • doStream

      protected reactor.core.publisher.Flux<NodeOutput> doStream(Map<String,Object> input, RunnableConfig runnableConfig)

    • buildNonStreamConfig

      protected RunnableConfig buildNonStreamConfig(RunnableConfig config)

    • buildStreamConfig

      protected RunnableConfig buildStreamConfig(RunnableConfig config)

    • applyExecutorConfig

      protected void applyExecutorConfig(RunnableConfig.Builder builder)
      Applies executor configuration to the RunnableConfig builder. This method sets the default executor for parallel nodes from the agent's configuration.
      Parameters:
      builder - the RunnableConfig builder to apply executor configuration to

    • buildMessageInput

      protected Map<String,Object> buildMessageInput(Object message)

    • initGraph

      protected abstract StateGraph initGraph() throws GraphStateException
      Throws:
      GraphStateException