Interface AgenticService<T,A>

Type Parameters:
T - the self-referencing builder type (for fluent chaining)
A - the type of the built agent proxy
All Known Subinterfaces:
ConditionalAgentService<T>, LoopAgentService<T>, ParallelAgentService<T>, ParallelMapperService<T>, PlannerBasedService<T>, SequentialAgentService<T>
All Known Implementing Classes:
ConditionalAgentServiceImpl, LoopAgentServiceImpl, ParallelAgentServiceImpl, ParallelMapperServiceImpl, PlannerBasedServiceImpl, SequentialAgentServiceImpl, SupervisorAgentServiceImpl
public interface AgenticService<T,A>
Fluent builder interface for configuring and assembling an agentic service composed of one or more sub-agents orchestrated by a planner.

  • Method Details

    • build

      A build()
      Builds the agentic service, returning a proxy that can be invoked to execute the configured workflow.
      Returns:
      the built agent proxy

    • subAgents

      T subAgents(Object... agents)
      Sets the sub-agents that participate in this agentic workflow.
      Parameters:
      agents - the sub-agents to orchestrate
      Returns:
      this builder for fluent chaining

    • subAgents

      T subAgents(Collection<?> agents)
      Sets the sub-agents that participate in this agentic workflow.
      Parameters:
      agents - a collection of sub-agents to orchestrate
      Returns:
      this builder for fluent chaining

    • beforeCall

      T beforeCall(Consumer<AgenticScope> beforeCall)
      Registers a callback invoked before each agent call, allowing inspection or modification of the AgenticScope (e.g. to inject variables).
      Parameters:
      beforeCall - the callback to invoke before each call
      Returns:
      this builder for fluent chaining

    • name

      T name(String name)
      Sets the name of this agentic service. If not provided, the method name of the agent interface is used.
      Parameters:
      name - the name of the agentic service
      Returns:
      this builder for fluent chaining

    • description

      T description(String description)
      Sets the description of this agentic service. The description should be clear enough for a language model to understand the agent's purpose.
      Parameters:
      description - the description of the agentic service
      Returns:
      this builder for fluent chaining

    • outputKey

      T outputKey(String outputKey)
      Sets the key under which the final output of this workflow is stored in the AgenticScope.
      Parameters:
      outputKey - the name of the output variable
      Returns:
      this builder for fluent chaining

    • outputKey

      T outputKey(Class<? extends TypedKey<?>> outputKey)
      Sets a strongly typed key for the output variable, enforcing type safety when retrieving the result from the AgenticScope. Use this as an alternative to outputKey(String).
      Parameters:
      outputKey - the class representing the typed output variable
      Returns:
      this builder for fluent chaining

    • output

      T output(Function<AgenticScope, Object> output)
      Sets a custom function to extract the final output from the AgenticScope at the end of the workflow. Use this when the output requires transformation or aggregation beyond a simple key lookup.
      Parameters:
      output - a function that receives the scope and returns the output
      Returns:
      this builder for fluent chaining

    • errorHandler

      T errorHandler(Function<ErrorContext, ErrorRecoveryResult> errorHandler)
      Registers an error handler that is invoked when a sub-agent fails. The handler receives an ErrorContext and returns an ErrorRecoveryResult indicating whether to propagate the exception, retry the failed agent, or return a fallback result.
      Parameters:
      errorHandler - the error handling function
      Returns:
      this builder for fluent chaining

    • compensateOnError

      T compensateOnError(boolean compensateOnError)
      Enables or disables cross-agent compensation. When enabled and any agent in the hierarchy fails, all previously successful tool invocations that have @CompensateFor actions are compensated in reverse chronological order, making the workflow's side effects atomic. Defaults to false.
      Parameters:
      compensateOnError - whether to enable cross-agent compensation
      Returns:
      this builder for fluent chaining

    • activationCondition

      T activationCondition(Predicate<AgenticScope> activationCondition)
      Sets the condition under which this agentic service runs when it is invoked as a subagent of another agentic system. When the condition is false the service is skipped: none of its subagents is invoked and nothing is written to the AgenticScope. The condition is ignored when this service is invoked directly. It can be evaluated more than once, so it must be free of side effects.
      Parameters:
      activationCondition - the predicate deciding whether this agentic service runs
      Returns:
      this builder for fluent chaining

    • activationCondition

      T activationCondition(String description, Predicate<AgenticScope> activationCondition)
      Sets the condition under which this agentic service runs when it is invoked as a subagent of another agentic system. When the condition is false the service is skipped: none of its subagents is invoked and nothing is written to the AgenticScope. The condition is ignored when this service is invoked directly. It can be evaluated more than once, so it must be free of side effects.
      Parameters:
      description - a human-readable description of the condition, used in logs, listeners and reports
      activationCondition - the predicate deciding whether this agentic service runs
      Returns:
      this builder for fluent chaining

    • listener

      T listener(AgentListener listeners)
      Registers an AgentListener to observe agent invocations, tool executions, and lifecycle events within this agentic service.
      Parameters:
      listeners - the listener to register
      Returns:
      this builder for fluent chaining