Module agentforge4j.tools.http
Package com.agentforge4j.tools.http

Record Class HttpEndpointDefinition

java.lang.Object
java.lang.Record
com.agentforge4j.tools.http.HttpEndpointDefinition
Record Components:
capability - <domain>.<verb_object> logical id, lowercase snake_case; stable and unique within the provider, and used as the remoteToolName
displayName - human-readable name, or null
description - human-readable description, or null
mutating - whether invoking this endpoint may mutate remote state; surfaced as the realised ToolRiskMetadata signal. Never null on a constructed instance: null is accepted only as the wire/positional-constructor spelling of "absent" (an HTTP_TOOL integration JSON config that omits the field, or a direct positional-constructor caller passing null) and is normalized to true — the highest safe risk — before the object exists, so a definition that omits the signal is treated as conservative. Java callers should prefer HttpEndpointDefinition.Builder.withMutating(boolean), which takes a non-null primitive and cannot express "absent" at all
method - HTTP method
urlTemplate - absolute http/https URL with {name} placeholders
inputSchema - JSON Schema for the arguments; non-null (convention additionalProperties:false)
outputSchema - JSON Schema for the result, or null if unknown
queryArgs - argument names routed to the query string
bodyMode - how the request body is formed from the leftover arguments
staticHeaders - fixed, non-secret headers (Content-Type, Accept, API-version, ...)
secretHeaders - header name to secret-reference key; resolved at invoke, never inlined
timeout - endpoint-level timeout ceiling, or null; restricts, never expands
maxRetries - endpoint-level retry cap, or null when unset; restricts, never expands
retryNonIdempotent - opt-in to retry POST/PATCH; meaningless on other methods
maxResponseBytes - response body read cap, or null to use the provider default
public record HttpEndpointDefinition(String capability, String displayName, String description, Boolean mutating, HttpMethod method, String urlTemplate, com.fasterxml.jackson.databind.JsonNode inputSchema, com.fasterxml.jackson.databind.JsonNode outputSchema, Set<String> queryArgs, BodyMode bodyMode, Map<String,String> staticHeaders, Map<String,String> secretHeaders, Duration timeout, Integer maxRetries, boolean retryNonIdempotent, Long maxResponseBytes) extends Record
Code-defined binding of a logical tool capability to a single HTTP endpoint.

Immutable; supplied by the consumer to HttpToolProvider. Per-field invariants are checked here at construction; cross-field rules that need the provider's view (capability uniqueness, argument disposition, method/body legality, secret-header consistency) are enforced by HttpToolProvider's constructor so a bad set of definitions fails fast at wiring time.

  • Constructor Details

    • HttpEndpointDefinition

      public HttpEndpointDefinition(String capability, String displayName, String description, Boolean mutating, HttpMethod method, String urlTemplate, com.fasterxml.jackson.databind.JsonNode inputSchema, com.fasterxml.jackson.databind.JsonNode outputSchema, Set<String> queryArgs, BodyMode bodyMode, Map<String,String> staticHeaders, Map<String,String> secretHeaders, Duration timeout, Integer maxRetries, boolean retryNonIdempotent, Long maxResponseBytes)
      Validates per-field invariants and defensively copies the collections.

  • Method Details

    • builder

      public static HttpEndpointDefinition.Builder builder()
      Returns a new HttpEndpointDefinition.Builder for assembling an HttpEndpointDefinition without 16 positional constructor arguments. The required fields (capability, method, urlTemplate, inputSchema, bodyMode) are validated when HttpEndpointDefinition.Builder.build() delegates to the canonical constructor; every other field may be left unset and takes the same default the canonical constructor already applies to a null argument.
      Returns:
      new builder; never null

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • capability

      public String capability()
      Returns the value of the capability record component.
      Returns:
      the value of the capability record component

    • displayName

      public String displayName()
      Returns the value of the displayName record component.
      Returns:
      the value of the displayName record component

    • description

      public String description()
      Returns the value of the description record component.
      Returns:
      the value of the description record component

    • mutating

      public Boolean mutating()
      Returns the value of the mutating record component.
      Returns:
      the value of the mutating record component

    • method

      public HttpMethod method()
      Returns the value of the method record component.
      Returns:
      the value of the method record component

    • urlTemplate

      public String urlTemplate()
      Returns the value of the urlTemplate record component.
      Returns:
      the value of the urlTemplate record component

    • inputSchema

      public com.fasterxml.jackson.databind.JsonNode inputSchema()
      Returns the value of the inputSchema record component.
      Returns:
      the value of the inputSchema record component

    • outputSchema

      public com.fasterxml.jackson.databind.JsonNode outputSchema()
      Returns the value of the outputSchema record component.
      Returns:
      the value of the outputSchema record component

    • queryArgs

      public Set<String> queryArgs()
      Returns the value of the queryArgs record component.
      Returns:
      the value of the queryArgs record component

    • bodyMode

      public BodyMode bodyMode()
      Returns the value of the bodyMode record component.
      Returns:
      the value of the bodyMode record component

    • staticHeaders

      public Map<String,String> staticHeaders()
      Returns the value of the staticHeaders record component.
      Returns:
      the value of the staticHeaders record component

    • secretHeaders

      public Map<String,String> secretHeaders()
      Returns the value of the secretHeaders record component.
      Returns:
      the value of the secretHeaders record component

    • timeout

      public Duration timeout()
      Returns the value of the timeout record component.
      Returns:
      the value of the timeout record component

    • maxRetries

      public Integer maxRetries()
      Returns the value of the maxRetries record component.
      Returns:
      the value of the maxRetries record component

    • retryNonIdempotent

      public boolean retryNonIdempotent()
      Returns the value of the retryNonIdempotent record component.
      Returns:
      the value of the retryNonIdempotent record component

    • maxResponseBytes

      public Long maxResponseBytes()
      Returns the value of the maxResponseBytes record component.
      Returns:
      the value of the maxResponseBytes record component