Module agentforge4j.bootstrap
Package com.agentforge4j.bootstrap

Class AgentForge4jBootstrap.Builder

java.lang.Object
com.agentforge4j.bootstrap.AgentForge4jBootstrap.Builder
Enclosing class:
AgentForge4jBootstrap
public static final class AgentForge4jBootstrap.Builder extends Object
Builder for AgentForge4j. Obtain via AgentForge4jBootstrap.defaults().

All with*(null) calls throw IllegalArgumentException immediately — passing null is always a bug. To restore a default, build a new instance.

withLlmProvider(LlmProviderConfig) is additive across providers and last-write-wins within a provider key. All other with* methods are last-write-wins.

  • Method Details

    • withClock

      public AgentForge4jBootstrap.Builder withClock(Clock clock)
      Overrides the clock used for timestamps on state updates and events.
      Parameters:
      clock - clock instance; must not be null
      Returns:
      this builder

    • withObjectMapper

      public AgentForge4jBootstrap.Builder withObjectMapper(com.fasterxml.jackson.databind.ObjectMapper objectMapper)
      Overrides the Jackson ObjectMapper used for configuration loading and LLM parsing.
      Parameters:
      objectMapper - mapper instance; must not be null
      Returns:
      this builder

    • withAgentRepository

      public AgentForge4jBootstrap.Builder withAgentRepository(AgentRepository agentRepository)
      Overrides the agent definition repository.
      Parameters:
      agentRepository - repository instance; must not be null
      Returns:
      this builder

    • withWorkflowRepository

      public AgentForge4jBootstrap.Builder withWorkflowRepository(WorkflowRepository workflowRepository)
      Overrides the workflow definition repository.
      Parameters:
      workflowRepository - repository instance; must not be null
      Returns:
      this builder

    • withWorkflowStateRepository

      public AgentForge4jBootstrap.Builder withWorkflowStateRepository(WorkflowStateRepository workflowStateRepository)
      Overrides persistence for workflow state between drives.
      Parameters:
      workflowStateRepository - repository instance; must not be null
      Returns:
      this builder

    • withWorkflowEventLog

      public AgentForge4jBootstrap.Builder withWorkflowEventLog(WorkflowEventLog workflowEventLog)
      Overrides the append-only workflow event log.
      Parameters:
      workflowEventLog - event log instance; must not be null
      Returns:
      this builder

    • withLlmClientResolver

      public AgentForge4jBootstrap.Builder withLlmClientResolver(LlmClientResolver llmClientResolver)
      Overrides the LLM client resolver.
      Parameters:
      llmClientResolver - resolver instance; must not be null
      Returns:
      this builder

    • withLlmRetryPolicy

      public AgentForge4jBootstrap.Builder withLlmRetryPolicy(LlmRetryPolicy llmRetryPolicy)
      Configures the LLM retry policy. When maxAttempts > 1, the assembled LlmClientResolver is automatically wrapped with RetryingLlmClientResolver using this policy.

      Has no effect if withLlmClientResolver(LlmClientResolver) was also called — an explicit resolver is never wrapped automatically.

      When maxAttempts <= 1 the policy is stored but no wrapping occurs (one attempt means no retry).

      Parameters:
      llmRetryPolicy - retry policy; must not be null
      Returns:
      this builder

    • withContextRenderer

      public AgentForge4jBootstrap.Builder withContextRenderer(ContextRenderer contextRenderer)
      Overrides the agent input context renderer.
      Parameters:
      contextRenderer - renderer instance; must not be null
      Returns:
      this builder

    • withLlmCommandParser

      public AgentForge4jBootstrap.Builder withLlmCommandParser(LlmCommandParser llmCommandParser)
      Overrides the LLM command response parser.
      Parameters:
      llmCommandParser - parser instance; must not be null
      Returns:
      this builder

    • withEventRecorder

      public AgentForge4jBootstrap.Builder withEventRecorder(EventRecorder eventRecorder)
      Overrides the shared workflow event recorder.
      Parameters:
      eventRecorder - recorder instance; must not be null
      Returns:
      this builder

    • withFileSink

      public AgentForge4jBootstrap.Builder withFileSink(FileSink fileSink)
      Overrides where CreateFileCommand content is written.
      Parameters:
      fileSink - file sink instance; must not be null
      Returns:
      this builder

    • withFileSinkPath

      public AgentForge4jBootstrap.Builder withFileSinkPath(Path fileSinkPath)
      Overrides where CreateFileCommand content is written.
      Parameters:
      fileSinkPath - path used to create a LocalFileSink instance
      Returns:
      this builder

    • withLlmProviderSelectionStrategy

      public AgentForge4jBootstrap.Builder withLlmProviderSelectionStrategy(LlmProviderSelectionStrategy strategy)
      Overrides the strategy for selecting an LLM provider from agent preferences.
      Parameters:
      strategy - selection strategy; must not be null
      Returns:
      this builder

    • withAgentInvoker

      public AgentForge4jBootstrap.Builder withAgentInvoker(AgentInvoker agentInvoker)
      Overrides the AgentInvoker used for agent and SPAR steps.
      Parameters:
      agentInvoker - invoker instance; must not be null
      Returns:
      this builder

    • withLlmCallObserver

      public AgentForge4jBootstrap.Builder withLlmCallObserver(LlmCallObserver llmCallObserver)
      Overrides the observer invoked after each completed LLM call.
      Parameters:
      llmCallObserver - observer instance; must not be null
      Returns:
      this builder

    • withRunExecutionInterceptor

      public AgentForge4jBootstrap.Builder withRunExecutionInterceptor(RunExecutionInterceptor runExecutionInterceptor)
      Registers a control interceptor fired before a run enters main execution and before each LLM call. Either hook may throw ExecutionBlockedException to block. Defaults to a no-op, so behaviour is unchanged when not set.
      Parameters:
      runExecutionInterceptor - interceptor instance; must not be null
      Returns:
      this builder

    • withModelTierResolver

      public AgentForge4jBootstrap.Builder withModelTierResolver(ModelTierResolver modelTierResolver)
      Overrides the resolver that maps a capability tier to a concrete model per provider. When not set, a ConfigModelTierResolver built from the shipped defaults merged with any agentforge4j.llm.model-tiers.<provider>.<tier> overrides is used.
      Parameters:
      modelTierResolver - resolver instance; must not be null
      Returns:
      this builder

    • withRequirementResolver

      public AgentForge4jBootstrap.Builder withRequirementResolver(RequirementResolver requirementResolver)
      Overrides the resolver consulted for declared workflow requirements at the run-start checkpoint and at deferred first use. When not set, the runtime defaults to the in-process DefaultRequirementResolver (default-or-empty), preserving the fail-fast guarantee out of the box. The embedding application supplies a store-backed resolver here.
      Parameters:
      requirementResolver - resolver instance; must not be null
      Returns:
      this builder

    • withArtifactValidators

      public AgentForge4jBootstrap.Builder withArtifactValidators(List<ArtifactValidator> artifactValidators)
      Registers additional ArtifactValidators a VALIDATE step may select by id. These are appended to the built-in agent-bundle validator (which is always present so shipped agent-bundle workflows keep working); a supplied validator that reuses an already-registered id fails fast at runtime assembly.
      Parameters:
      artifactValidators - validators to add; must not be null
      Returns:
      this builder

    • withContextAggregators

      public AgentForge4jBootstrap.Builder withContextAggregators(List<ContextAggregator> contextAggregators)
      Registers additional ContextAggregators an AGGREGATE step may select by id. These are appended to the built-in aggregators discovered via ServiceLoader; a supplied aggregator that reuses an already-registered id fails fast at runtime assembly.
      Parameters:
      contextAggregators - aggregators to add; must not be null
      Returns:
      this builder

    • withToolProviders

      public AgentForge4jBootstrap.Builder withToolProviders(List<ToolProvider> toolProviders)
      Provides pre-built tool providers (for example MCP servers) to expose to the runtime. Configuring any tool support enables the tool-execution chokepoint and registers the TOOL_INVOCATION handler; with none configured, tool invocation is unavailable and behaviour is unchanged.

      These providers are merged with any configured integrations source into the single IntegrationToolProviderResolver; the two coexist unless they expose the same capability, which fails fast. Has no effect if withToolProviderResolver(ToolProviderResolver) is set — an explicit resolver is the sole resolver.

      Trust boundary. Providers supplied here are trusted embedder code: the ToolSourceKind their descriptors declare is taken at face value by the secure default ToolPolicy, so a provider that declares an in-process source is allowed by default. Supply a custom ToolPolicy to gate providers whose declared kind you do not control.

      Parameters:
      toolProviders - providers to expose; must not be null
      Returns:
      this builder

    • withToolProviderResolver

      public AgentForge4jBootstrap.Builder withToolProviderResolver(ToolProviderResolver toolProviderResolver)
      Overrides the capability resolver (for example a binding-aware resolver supplied by the embedding application). When set, it is the sole resolver and withToolProviders(List) is not used to build one.
      Parameters:
      toolProviderResolver - resolver instance; must not be null
      Returns:
      this builder

    • withToolPolicy

      public AgentForge4jBootstrap.Builder withToolPolicy(ToolPolicy toolPolicy)
      Overrides the tool policy. Defaults to the secure-by-default policy (SecureDefaultToolPolicy), which denies remote-network and local-process tools unless an explicit policy (ToolPolicy.allowAll() or a custom one) opts in.
      Parameters:
      toolPolicy - policy instance; must not be null
      Returns:
      this builder

    • withPendingToolInvocationStore

      public AgentForge4jBootstrap.Builder withPendingToolInvocationStore(PendingToolInvocationStore pendingToolInvocationStore)
      Overrides the pending tool invocation store. Defaults to an in-memory store.
      Parameters:
      pendingToolInvocationStore - store instance; must not be null
      Returns:
      this builder

    • withToolExecutionOptions

      public AgentForge4jBootstrap.Builder withToolExecutionOptions(ToolExecutionOptions toolExecutionOptions)
      Overrides the tool execution options (authoritative timeout, retries, backoff). Defaults to ToolExecutionOptions.defaults().
      Parameters:
      toolExecutionOptions - options instance; must not be null
      Returns:
      this builder

    • withAllowPrivateNetworks

      public AgentForge4jBootstrap.Builder withAllowPrivateNetworks(boolean allowPrivateNetworks)
      Lifts the outbound-egress guard's private/loopback/link-local/cloud-metadata blocks for HTTP and MCP streamable-HTTP tools. Development only — enabling this disables the cloud-metadata-IP (SSRF) protection. The http/https scheme allowlist still applies. Defaults to false (fail-closed).
      Parameters:
      allowPrivateNetworks - whether to allow private/loopback network targets
      Returns:
      this builder

    • withIntegrationsDir

      public AgentForge4jBootstrap.Builder withIntegrationsDir(Path integrationsDir)
      Opts in to loading integration definitions from top-level *.json files in the given directory at build time. Loaded definitions are saved into the integration repository and resolved into tool providers through the discovered IntegrationToolProviderFactory contributions, enabling tool support.

      Has no effect if withToolProviderResolver(ToolProviderResolver) is also set — an explicit resolver is the sole resolver. Coexists with withToolProviders(List): the two sources are merged into one resolver and only a shared capability fails fast.

      Parameters:
      integrationsDir - integrations root directory; must be an existing directory
      Returns:
      this builder

    • withIntegrationConfigLoader

      public AgentForge4jBootstrap.Builder withIntegrationConfigLoader(IntegrationConfigLoader integrationConfigLoader)
      Overrides the integration definition loader. When set, it is used instead of the filesystem loader over withIntegrationsDir(Path).
      Parameters:
      integrationConfigLoader - loader instance; must not be null
      Returns:
      this builder

    • withIntegrationRepository

      public AgentForge4jBootstrap.Builder withIntegrationRepository(MutableIntegrationRepository integrationRepository)
      Overrides the integration repository that loaded definitions are saved into and the capability resolver reads from. Defaults to an in-memory repository.
      Parameters:
      integrationRepository - repository instance; must not be null
      Returns:
      this builder

    • withToolProviderFactory

      public AgentForge4jBootstrap.Builder withToolProviderFactory(ToolProviderFactory toolProviderFactory)
      Overrides the factory that realises integration definitions as tool providers. Defaults to the ServiceLoaderToolProviderFactory aggregating the discovered per-type contributions.
      Parameters:
      toolProviderFactory - factory instance; must not be null
      Returns:
      this builder

    • withSecretResolver

      public AgentForge4jBootstrap.Builder withSecretResolver(SecretResolver secretResolver)
      Overrides the resolver that turns a secret-reference key into its live value at invoke time (for example an HTTP integration's secretHeaders). Defaults to EnvironmentSecretResolver, which reads process environment variables then system properties. An embedding application supplies its own implementation backed by its secret store.
      Parameters:
      secretResolver - resolver instance; must not be null
      Returns:
      this builder

    • withMaxNestingDepth

      public AgentForge4jBootstrap.Builder withMaxNestingDepth(int maxNestingDepth)
      Sets the maximum nested workflow depth forwarded to WorkflowRuntimeBuilder.
      Parameters:
      maxNestingDepth - maximum nesting depth (at least 1)
      Returns:
      this builder

    • withAgentsDir

      public AgentForge4jBootstrap.Builder withAgentsDir(Path agentsDir)
      Opts in to loading agents from the given filesystem directory at build time.
      Parameters:
      agentsDir - agents root directory; must not be null
      Returns:
      this builder

    • withWorkflowsDir

      public AgentForge4jBootstrap.Builder withWorkflowsDir(Path workflowsDir)
      Opts in to loading workflows from the given filesystem directory at build time.
      Parameters:
      workflowsDir - workflows root directory; must not be null
      Returns:
      this builder

    • withLoadShippedAgents

      public AgentForge4jBootstrap.Builder withLoadShippedAgents(boolean loadShippedAgents)
      Enables or disables loading shipped agents from the classpath.
      Parameters:
      loadShippedAgents - true to load shipped agents
      Returns:
      this builder

    • withLoadShippedWorkflows

      public AgentForge4jBootstrap.Builder withLoadShippedWorkflows(boolean loadShippedWorkflows)
      Enables or disables loading shipped workflows from the classpath.
      Parameters:
      loadShippedWorkflows - true to load shipped workflows
      Returns:
      this builder

    • withCacheEnabled

      public AgentForge4jBootstrap.Builder withCacheEnabled(boolean cacheEnabled)
      Enables or disables prompt-layer caching on the default AgentInvoker.
      Parameters:
      cacheEnabled - true to enable prompt cache boundaries on LLM requests
      Returns:
      this builder

    • withLlmProvider

      public AgentForge4jBootstrap.Builder withLlmProvider(LlmProviderConfig config)
      Adds or replaces programmatic LLM provider configuration. Additive across provider keys; last-write-wins within the same provider key.
      Parameters:
      config - provider configuration; must not be null
      Returns:
      this builder

    • withLlmSecretResolver

      public AgentForge4jBootstrap.Builder withLlmSecretResolver(LlmSecretResolver llmSecretResolver)
      Overrides the LlmSecretResolver used to resolve provider credential references. The default (EnvSystemPropertyLlmSecretResolver) passes literal credentials through and resolves env:/sysprop: references from the process environment / system properties.
      Parameters:
      llmSecretResolver - resolver instance; must not be null
      Returns:
      this builder

    • build

      public AgentForge4j build()
      Builds the AgentForge4j facade, assembling all components with defaults for any overrides not set.
      Returns:
      immutable facade; never null
      Throws:
      IllegalStateException - if assembly fails (e.g. loading throws)