Interface Thinker<I extends ThinkerInput, O extends ThinkerOutput<? extends Reasoning>>

Type Parameters:
I - Input type - must extend ThinkerInput for uniform query handling
O - Output type - must extend ThinkerOutput for uniform response handling
All Superinterfaces:
ConversationCarrier, GuardedExecution, Identifiable, Job<O>, ModelDependent, ModelDependentTool<I,O>, Orchestrator<I,O>, ScopeAuthority, Tool<I,O>
All Known Implementing Classes:
AbstractThinker, AbstractToollessThinker, CaseAgent, ChatThinker, DemoAgent, EPOThinker, LiteratureAggregator, OrderAgent, ReactiveThinker, SelectingAgent, SingleObjectiveThinker, SubThinker, UsptoOdpThinker
public interface Thinker<I extends ThinkerInput, O extends ThinkerOutput<? extends Reasoning>> extends Orchestrator<I,O>, ModelDependentTool<I,O>, ConversationCarrier
Interface for reasoning agents that coordinate tool execution.

Thinkers are specialized tools that solve problems by iteratively using available tools. They accept structured input like all tools, but their execution involves complex multi-step reasoning and tool orchestration.

Key difference from simple tools: Thinkers run conversation loops with LLMs and dynamically select which tools to use, while simple tools perform single operations.

Composition: Since thinkers are tools, they can be used by other thinkers, enabling hierarchical multi-agent systems where meta-agents coordinate specialist agents.

Since:
0.1 (2025-09-19)
Author:
Andrey Santrosyan

  • Method Details

    • isInteractive

      boolean isInteractive()
      Whether a human is waiting on this thinker's answers - a demand flavor pickers may weigh.

    • getDepth

      Depth getDepth()
      How much effort this thinker's calls ask for: its input's depth for a goal-directed thinker, its declared field for a reactive one. Stamped onto the conversation by ConversationService at obtain time, next to the grade.

    • getOutputDeclaration

      OutputDeclaration getOutputDeclaration()
      How much answer this thinker's turns book: an OutputSize rung or a raw count, declared in the constructor next to the grade. Null before the declaration; execution refuses a thinker that reaches it without one. Stamped onto the conversation by ConversationService at obtain time.

    • addTool

      void addTool(Class<? extends Tool> toolClass)
      Adds a tool to this thinker's available tools. The tool will be registered and can be invoked by the LLM.
      Parameters:
      toolClass - the tool class to add

    • addTool

      void addTool(ToolProvider provider)
      Adds a ToolProvider to this thinker's available tools. Mirror of addTool(Class) for providers that are not class-backed (e.g. MCP-bound).
      Parameters:
      provider - the provider to add

    • removeTool

      void removeTool(Class<? extends Tool> toolClass)
      Removes a tool from this thinker's available tools.
      Parameters:
      toolClass - the tool class to remove

    • removeTool

      void removeTool(String toolName)
      Removes a tool by registered name. Mirror of removeTool(Class) for providers without an associated Java class.
      Parameters:
      toolName - the tool name to remove

    • hasTool

      boolean hasTool(Class<? extends Tool> toolClass)
      Checks if a tool class is registered with this thinker.
      Parameters:
      toolClass - the tool class to check
      Returns:
      true if the tool is registered

    • hasTool

      boolean hasTool(String toolName)
      Checks if a tool name is registered with this thinker.
      Parameters:
      toolName - the tool name to check
      Returns:
      true if the tool is registered

    • getTools

      Collection<Class<? extends Tool>> getTools()
      Gets all currently registered tool classes.
      Returns:
      unmodifiable collection of tool classes

    • getProviders

      Collection<ToolProvider> getProviders()
      Gets all currently registered providers (class-based and otherwise).
      Returns:
      unmodifiable collection of providers

    • buildToolDefinitionBlocks

      List<ContentBlocks.ToolDefinitionBlock> buildToolDefinitionBlocks()
      Builds tool definition blocks for all registered tools. Used for conversation context when loading from persistence.
      Returns:
      list of tool definition blocks

    • cacheAllMessages

      boolean cacheAllMessages()
      Returns whether all conversation messages should be cached. When enabled, every message added to the conversation context will have caching enabled automatically (if supported by the LLM provider).
      Returns:
      true to cache all messages, false for manual control

    • setCacheAllMessages

      void setCacheAllMessages(boolean cacheAllMessages)
      Sets whether all conversation messages should be cached.
      Parameters:
      cacheAllMessages - true to enable caching for all messages

    • isInvokedAsTool

      boolean isInvokedAsTool()
      Returns whether this thinker was invoked as a tool by another thinker. When true, the thinker should not stream results directly to the user - the results will be returned to the parent thinker as a tool result.
      Returns:
      true if invoked as a tool, false if running standalone

    • setInvokedAsTool

      void setInvokedAsTool(boolean invokedAsTool)
      Marks this thinker as being invoked as a tool. Set automatically by the parent thinker when using this thinker as a tool.
      Parameters:
      invokedAsTool - true if being used as a tool

    • getRetainDuration

      Duration getRetainDuration()
      Gets the retention duration for intermediate releases (between tool calls). Controls how long the conversation stays in memory during active processing.
      Returns:
      the intermediate retention duration

    • setRetainDuration

      void setRetainDuration(Duration retainDuration)
      Sets the retention duration for intermediate releases.
      Parameters:
      retainDuration - the intermediate retention duration

    • getFinalRetainDuration

      Duration getFinalRetainDuration()
      Gets the retention duration after the thinker finishes (execute()'s finally block). Controls how long the conversation persists in memory after the thinker completes.
      Returns:
      the final retention duration

    • setFinalRetainDuration

      void setFinalRetainDuration(Duration finalRetainDuration)
      Sets the retention duration after the thinker finishes.
      Parameters:
      finalRetainDuration - the final retention duration

    • getConversationId

      String getConversationId()
      Gets the conversation ID for this thinker. By default returns the job ID for new conversations. Can be set to resume existing conversations.
      Returns:
      the conversation ID (job ID if not explicitly set)

    • setConversationId

      void setConversationId(String conversationId)
      Adopts an existing conversation: the thinker resumes the conversation with this id, and obtaining it fails when no store holds it - a resume that silently minted an empty conversation would leave the model defending reasoning it can no longer see.
      Specified by:
      setConversationId in interface ConversationCarrier
      Parameters:
      conversationId - the existing conversation ID to resume

    • mintConversationId

      String mintConversationId()
      Mints a durable identity for a brand-new conversation, decoupled from job lineage. The id follows the framework's readable shape - the thinker's class name, a conv marker, and a short random tail (e.g. ChatThinker-conv-a26f-52b01fa3bd75) - so DB rows and logs stay scannable and a minted id is never mistaken for a job id. The conversation is created fresh under this id and every later turn adopts it via setConversationId(String). Thinkers that call neither keep the default: a temporary conversation keyed by the thinker's own job id.
      Returns:
      the minted conversation ID

    • isConversationMinted

      boolean isConversationMinted()
      Whether this thinker's conversation identity was minted fresh (as opposed to adopted or left on the temporary jobId default). A minted conversation has no durable record yet: its first user-message save CREATES the record - titled and embedded from that message, exactly once - and every later save is an update.
      Returns:
      true when mintConversationId() named this conversation