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

    • 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