程序包 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

      @Deprecated public ReActAgent.Builder checkRunning(boolean checkRunning)
      已过时。
      No longer enforced; per-session serialization handles concurrency.

    • 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

    • model

      public ReActAgent.Builder model(String modelId)
      Configures the model from a string id resolved via ModelRegistry: a named registration (ModelRegistry.register(String, Model)) or an extension provider pattern such as openai:gpt-5.5, dashscope:qwen-max, anthropic:claude-sonnet-4-5, gemini:gemini-2.0-flash, or ollama:llama3. Extension modules read API keys from their standard environment variables when auto-created.
      参数:
      modelId - registry id or provider:model string
      返回:
      this builder
      抛出:
      IllegalArgumentException - if the id cannot be resolved

    • 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

    • 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
      另请参阅:

    • middleware

      public ReActAgent.Builder middleware(MiddlewareBase middleware)
      Adds a middleware for intercepting agent execution.
      参数:
      middleware - the middleware to add
      返回:
      this builder instance for method chaining

    • middlewares

      public ReActAgent.Builder middlewares(List<? extends MiddlewareBase> middlewares)
      Adds multiple middlewares for intercepting agent execution.
      参数:
      middlewares - the list of middlewares to add
      返回:
      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

    • enableTaskList

      public ReActAgent.Builder enableTaskList()
      Enables the built-in task-list capability (todo_write tool + per-turn reminder).

      Equivalent to enableTaskList(true).

      返回:
      this builder for chaining

    • enableTaskList

      public ReActAgent.Builder enableTaskList(boolean enabled)
      Enables or disables the built-in task-list capability.

      When enabled, build() registers a todo_write tool (operating on AgentState.getTasksContext() with full-list-replace semantics) and a TaskReminderMiddleware that re-surfaces the current list before every reasoning step. Default OFF.

      参数:
      enabled - true to enable the task list
      返回:
      this builder for chaining

    • enablePendingToolRecovery

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

      When enabled, the agent automatically detects orphaned pending tool calls and patches them with synthetic error results before processing new input. 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
      另请参阅:

    • toolExecutionContext

      @Deprecated public ReActAgent.Builder toolExecutionContext(ToolExecutionContext toolExecutionContext)
      已过时。
      Use RuntimeContext with agent.call(msg, runtimeContext) or register POJOs directly via RuntimeContext.builder().put(Type, value).
      Sets the tool execution context for this agent.
      参数:
      toolExecutionContext - The tool execution context
      返回:
      This builder instance for method chaining

    • stateStore

      public ReActAgent.Builder stateStore(AgentStateStore stateStore)
      Sets the AgentStateStore backing automatic AgentState load (at construction) and save (after every successful call() and on graceful shutdown). When null, the agent runs purely in-memory and persistence is a no-op.

    • defaultSessionId

      public ReActAgent.Builder defaultSessionId(String sessionId)
      Sets the builder-time fallback sessionId used to persist agent_state when a call does not supply a sessionId on its RuntimeContext. Defaults to the agent name when unset. Per-call routing is via RuntimeContext.sessionId; this is only the bootstrap / single-tenant default.

    • maxRetries

      public ReActAgent.Builder maxRetries(int maxRetries)
      Sets the model-call retry budget (max attempts including the first try). Defaults to ModelConfig.DEFAULT_MAX_RETRIES when unset.

    • fallbackModel

      public ReActAgent.Builder fallbackModel(Model fallbackModel)
      Sets the fallback model invoked after the primary model exhausts its retry budget. Pass null to explicitly clear (no fallback).

    • fallbackModel

      public ReActAgent.Builder fallbackModel(String modelId)
      Convenience overload that resolves modelId via ModelRegistry.resolve(String) (named registration or provider:model pattern like openai:gpt-5.5, dashscope:qwen-max).
      抛出:
      IllegalArgumentException - if the id cannot be resolved

    • stopOnReject

      public ReActAgent.Builder stopOnReject(boolean stopOnReject)
      Controls whether a permission rejection of any tool call terminates the reasoning loop (instead of feeding the rejection back into the next reasoning round). Defaults to ReactConfig.DEFAULT_STOP_ON_REJECT.

    • permissionContext

      public ReActAgent.Builder permissionContext(PermissionContextState permissionContext)
      Sets the PermissionContextState consulted by the PermissionEngine during tool execution. When unset, an empty permission context is used (PASSTHROUGH for all tools).

    • longTermMemory

      @Deprecated(forRemoval=true, since="2.0.0") public ReActAgent.Builder longTermMemory(LongTermMemory longTermMemory)
      已过时, 待删除: 此 API 元素将从以后的版本中删除。
      since 2.0.0. Long-term memory is being redesigned around the upcoming reme base class. Hooks added through this path still work.

    • longTermMemoryMode

      @Deprecated(forRemoval=true, since="2.0.0") public ReActAgent.Builder longTermMemoryMode(LongTermMemoryMode mode)
      已过时, 待删除: 此 API 元素将从以后的版本中删除。
      since 2.0.0. See longTermMemory.

    • longTermMemoryAsyncRecord

      @Deprecated(forRemoval=true, since="2.0.0") public ReActAgent.Builder longTermMemoryAsyncRecord(boolean asyncRecord)
      已过时, 待删除: 此 API 元素将从以后的版本中删除。
      since 2.0.0. See longTermMemory.

    • knowledge

      @Deprecated(forRemoval=true, since="2.0.0") public ReActAgent.Builder knowledge(Knowledge knowledge)
      已过时, 待删除: 此 API 元素将从以后的版本中删除。
      since 2.0.0. RAG is being redesigned; legacy adapters remain functional.

    • knowledges

      @Deprecated(forRemoval=true, since="2.0.0") public ReActAgent.Builder knowledges(List<Knowledge> knowledges)
      已过时, 待删除: 此 API 元素将从以后的版本中删除。
      since 2.0.0. See knowledge(io.agentscope.core.rag.Knowledge).

    • ragMode

      @Deprecated(forRemoval=true, since="2.0.0") public ReActAgent.Builder ragMode(RAGMode mode)
      已过时, 待删除: 此 API 元素将从以后的版本中删除。
      since 2.0.0. See knowledge(io.agentscope.core.rag.Knowledge).

    • retrieveConfig

      @Deprecated(forRemoval=true, since="2.0.0") public ReActAgent.Builder retrieveConfig(RetrieveConfig config)
      已过时, 待删除: 此 API 元素将从以后的版本中删除。
      since 2.0.0. See knowledge(io.agentscope.core.rag.Knowledge).

    • skillBox

      @Deprecated(since="2.0.0") public ReActAgent.Builder skillBox(SkillBox skillBox)
      已过时。
      since 2.0.0. Skills now flow through skillRepository(io.agentscope.core.skill.repository.AgentSkillRepository) / skillRepositories; legacy SkillBox instances are still accepted for source compatibility, but combining a skillBox(...) with skillRepository(...) is untested — new code should prefer skillRepository(AgentSkillRepository).

    • skillRepository

      public ReActAgent.Builder skillRepository(AgentSkillRepository repo)
      Adds a single AgentSkillRepository to the layered skill stack. Multiple calls append in order from low to high priority — when two repositories expose a skill with the same AgentSkill.getName(), the later (higher priority) entry wins.

      If at least one repository is registered and dynamic skills remain enabled (see dynamicSkillsEnabled(boolean)), build() attaches a DynamicSkillMiddleware that rebuilds the skill prompt on every call().

    • skillRepositories

      public ReActAgent.Builder skillRepositories(List<AgentSkillRepository> repos)
      Replaces the current repository list with the supplied collection. null entries are dropped silently; passing null clears the list.

    • skillFilter

      public ReActAgent.Builder skillFilter(SkillFilter filter)
      Builder-time SkillFilter applied by the auto-installed DynamicSkillMiddleware. Defaults to SkillFilter.all() when unset.

    • dynamicSkillsEnabled

      public ReActAgent.Builder dynamicSkillsEnabled(boolean enabled)
      Toggles automatic installation of DynamicSkillMiddleware. Set to false when an external orchestrator (e.g. HarnessAgent) wants to attach its own subclass of DynamicSkillMiddleware or fall back to a static SkillBox. Defaults to true.

    • skillCodeExecutionEnabled

      public ReActAgent.Builder skillCodeExecutionEnabled(boolean enabled)
      Enables the code-execution prompt block emitted by AgentSkillPromptProvider. When on:
      • If every visible skill has an on-disk origin directory (e.g. produced by FileSystemSkillRepository), each <skill> entry includes a <files-root> child with the absolute path so the LLM can shell-execute scripts directly;
      • Otherwise the prompt falls back to a single uploadDir root.

      Only flip this on when the agent's toolkit has a shell-like tool wired in — otherwise the prompt will ask the model to do things it cannot. Defaults to false.

    • skillWorkDir

      public ReActAgent.Builder skillWorkDir(Path dir)
      Sets a stable working directory used by DynamicSkillMiddleware for uploadSkillFiles. Pass null (the default) to let the middleware mkdtemp a fresh directory on first reload and reuse it for the agent's lifetime.

    • fromAgent

      public static ReActAgent.Builder fromAgent(ReActAgent agent)
      Returns a new ReActAgent.Builder pre-populated with the given agent's observable configuration: name, description, system prompt, model, maxIters, generateOptions, and a defensive copy of the toolkit.

      Use to derive a related agent without re-specifying every field.

    • 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