程序包 io.agentscope.core

类 ReActAgent.Builder

java.lang.Object
io.agentscope.core.ReActAgent.Builder
封闭类:
ReActAgent
public static class ReActAgent.Builder extends Object

  • 方法详细资料

    • name

      public ReActAgent.Builder name(String name)
      Sets the name for this agent.
      参数:
      name - The agent name, must not be null
      返回:
      This builder instance for method chaining

    • description

      public ReActAgent.Builder description(String description)

    • checkRunning

      public ReActAgent.Builder checkRunning(boolean checkRunning)

    • sysPrompt

      public ReActAgent.Builder sysPrompt(String sysPrompt)
      Sets the system prompt for this agent.
      参数:
      sysPrompt - The system prompt, can be null or empty
      返回:
      This builder instance for method chaining

    • model

      public ReActAgent.Builder model(Model model)
      Sets the language model for this agent.
      参数:
      model - The language model to use for reasoning, must not be null
      返回:
      This builder instance for method chaining

    • toolkit

      public ReActAgent.Builder toolkit(Toolkit toolkit)
      Sets the toolkit containing available tools for this agent.
      参数:
      toolkit - The toolkit with available tools, must not be null
      返回:
      This builder instance for method chaining

    • memory

      public ReActAgent.Builder memory(Memory memory)
      Sets the memory for storing conversation history.
      参数:
      memory - The memory implementation, can be null (defaults to InMemoryMemory)
      返回:
      This builder instance for method chaining

    • maxIters

      public ReActAgent.Builder maxIters(int maxIters)
      Sets the maximum number of reasoning-acting iterations.
      参数:
      maxIters - Maximum iterations, must be positive
      返回:
      This builder instance for method chaining

    • hook

      public ReActAgent.Builder hook(Hook hook)
      Adds a hook for monitoring and intercepting agent execution events.

      Hooks can observe or modify events during reasoning, acting, and other phases. Multiple hooks can be added and will be executed in priority order (lower priority values execute first).

      参数:
      hook - The hook to add, must not be null
      返回:
      This builder instance for method chaining
      另请参阅:

    • hooks

      public ReActAgent.Builder hooks(List<Hook> hooks)
      Adds multiple hooks for monitoring and intercepting agent execution events.

      Hooks can observe or modify events during reasoning, acting, and other phases. All hooks will be executed in priority order (lower priority values execute first).

      参数:
      hooks - The list of hooks to add, must not be null
      返回:
      This builder instance for method chaining
      另请参阅:

    • enableMetaTool

      public ReActAgent.Builder enableMetaTool(boolean enableMetaTool)
      Enables or disables the meta-tool functionality.

      When enabled, the toolkit will automatically register a meta-tool that provides information about available tools to the agent. This can help the agent understand what tools are available without relying solely on the system prompt.

      参数:
      enableMetaTool - true to enable meta-tool, false to disable
      返回:
      This builder instance for method chaining

    • enablePendingToolRecovery

      public ReActAgent.Builder enablePendingToolRecovery(boolean enable)
      Enables or disables automatic recovery from orphaned pending tool calls.

      When enabled , a PendingToolRecoveryHook is automatically registered to detect and patch orphaned pending tool calls with synthetic error results before agent processing begins. This prevents IllegalStateException when tool execution fails, times out, or is interrupted.

      Disable this if you prefer to handle pending tool calls manually, for example through HITL (Human-in-the-loop) mechanisms or custom error handling strategies.

      参数:
      enable - true to enable auto-recovery, false to disable
      返回:
      This builder instance for method chaining
      另请参阅:

    • modelExecutionConfig

      public ReActAgent.Builder modelExecutionConfig(ExecutionConfig modelExecutionConfig)
      Sets the execution configuration for model API calls.

      This configuration controls timeout, retry behavior, and backoff strategy for model requests during the reasoning phase. If not set, the agent will use the model's default execution configuration.

      参数:
      modelExecutionConfig - The execution configuration for model calls, can be null
      返回:
      This builder instance for method chaining
      另请参阅:

    • toolExecutionConfig

      public ReActAgent.Builder toolExecutionConfig(ExecutionConfig toolExecutionConfig)
      Sets the execution configuration for tool executions.

      This configuration controls timeout, retry behavior, and backoff strategy for tool calls during the acting phase. If not set, the toolkit will use its default execution configuration.

      参数:
      toolExecutionConfig - The execution configuration for tool calls, can be null
      返回:
      This builder instance for method chaining
      另请参阅:

    • generateOptions

      public ReActAgent.Builder generateOptions(GenerateOptions generateOptions)
      Sets the generation options for model API calls.

      This configuration controls LLM generation parameters such as temperature, topP, maxTokens, frequencyPenalty, presencePenalty, etc. These options are passed to the model during the reasoning phase.

      Example usage: 

      
 ReActAgent agent = ReActAgent.builder()
     .name("assistant")
     .model(model)
     .generateOptions(GenerateOptions.builder()
         .temperature(0.7)
         .topP(0.9)
         .maxTokens(1000)
         .build())
     .build();

      Note: If both generateOptions and modelExecutionConfig are set, the modelExecutionConfig's executionConfig will be merged into the generateOptions, with modelExecutionConfig taking precedence for execution settings.

      参数:
      generateOptions - The generation options for model calls, can be null
      返回:
      This builder instance for method chaining
      另请参阅:

    • structuredOutputReminder

      public ReActAgent.Builder structuredOutputReminder(StructuredOutputReminder reminder)
      Sets the structured output enforcement mode.
      参数:
      reminder - The structured output reminder mode, must not be null
      返回:
      This builder instance for method chaining

    • planNotebook

      public ReActAgent.Builder planNotebook(PlanNotebook planNotebook)
      Sets the PlanNotebook for plan-based task execution.

      When provided, the PlanNotebook will be integrated into the agent:

      • Plan management tools will be automatically registered to the toolkit
      • A hook will be added to inject plan hints before each reasoning step
      参数:
      planNotebook - The configured PlanNotebook instance, can be null
      返回:
      This builder instance for method chaining

    • skillBox

      public ReActAgent.Builder skillBox(SkillBox skillBox)
      Sets the skill box for this agent.

      The skill box is used to manage the skills for this agent. It will be used to register the skills to the toolkit.

      • Skill loader tools will be automatically registered to the toolkit
      • A skill hook will be added to inject skill prompts and manage skill activation
      参数:
      skillBox - The skill box to use for this agent
      返回:
      This builder instance for method chaining

    • longTermMemory

      public ReActAgent.Builder longTermMemory(LongTermMemory longTermMemory)
      Sets the long-term memory for this agent.

      Long-term memory enables the agent to remember information across sessions. It can be used in combination with longTermMemoryMode(LongTermMemoryMode) to control whether memory management is automatic, agent-controlled, or both.

      参数:
      longTermMemory - The long-term memory implementation
      返回:
      This builder instance for method chaining
      另请参阅:

    • longTermMemoryMode

      public ReActAgent.Builder longTermMemoryMode(LongTermMemoryMode mode)
      Sets the long-term memory mode.

      This determines how long-term memory is integrated with the agent:

      • AGENT_CONTROL: Memory tools are registered for agent to call
      • STATIC_CONTROL: Framework automatically retrieves/records memory
      • BOTH: Combines both approaches (default)
      参数:
      mode - The long-term memory mode
      返回:
      This builder instance for method chaining
      另请参阅:

    • longTermMemoryAsyncRecord

      public ReActAgent.Builder longTermMemoryAsyncRecord(boolean asyncRecord)
      Sets whether long-term memory recording should be performed asynchronously.

      When enabled, the framework will record memories to long-term storage in a fire-and-forget manner, without blocking the agent's main execution flow. This improves response latency but means memory persistence is not guaranteed before the agent returns its response.

      When disabled (default), the framework waits for the recording operation to complete before returning the agent's response. This ensures memory persistence is finalized but may increase response latency.

      Note: This setting only affects the static control mode (STATIC_CONTROL, BOTH). Agent-controlled recording through tools is always synchronous.

      参数:
      asyncRecord - Whether to record memories asynchronously
      返回:
      This builder instance for method chaining

    • statePersistence

      public ReActAgent.Builder statePersistence(StatePersistence statePersistence)
      Sets the state persistence configuration.

      Use this to control which components' state is managed by the agent during saveTo/loadFrom operations. By default, all components are managed.

      Example usage: 

      
 ReActAgent agent = ReActAgent.builder()
     .name("assistant")
     .model(model)
     .statePersistence(StatePersistence.builder()
         .planNotebookManaged(false)  // Let user manage PlanNotebook separately
         .build())
     .build();
      参数:
      statePersistence - The state persistence configuration
      返回:
      This builder instance for method chaining
      另请参阅:

    • enablePlan

      public ReActAgent.Builder enablePlan()
      Enables plan functionality with default configuration.

      This is a convenience method equivalent to: 

      
 planNotebook(PlanNotebook.builder().build())
      返回:
      This builder instance for method chaining

    • knowledge

      public ReActAgent.Builder knowledge(Knowledge knowledge)
      Adds a knowledge base for RAG (Retrieval-Augmented Generation).
      参数:
      knowledge - The knowledge base to add
      返回:
      This builder instance for method chaining

    • knowledges

      public ReActAgent.Builder knowledges(List<Knowledge> knowledges)
      Adds multiple knowledge bases for RAG.
      参数:
      knowledges - The list of knowledge bases to add
      返回:
      This builder instance for method chaining

    • ragMode

      public ReActAgent.Builder ragMode(RAGMode mode)
      Sets the RAG mode.
      参数:
      mode - The RAG mode (GENERIC, AGENTIC, or NONE)
      返回:
      This builder instance for method chaining

    • retrieveConfig

      public ReActAgent.Builder retrieveConfig(RetrieveConfig config)
      Sets the retrieve configuration for RAG.
      参数:
      config - The retrieve configuration
      返回:
      This builder instance for method chaining

    • toolExecutionContext

      public ReActAgent.Builder toolExecutionContext(ToolExecutionContext toolExecutionContext)
      Sets the tool execution context for this agent.

      This context will be passed to all tools invoked by this agent and can include user identity, session information, permissions, and other metadata. The context from this agent level will override toolkit-level context but can be overridden by call-level context.

      参数:
      toolExecutionContext - The tool execution context
      返回:
      This builder instance for method chaining

    • build

      public ReActAgent build()
      Builds and returns a new ReActAgent instance with the configured settings.
      返回:
      A new ReActAgent instance
      抛出:
      IllegalArgumentException - if required parameters are missing or invalid