Interface AgenticHarness

All Superinterfaces:
AutoCloseable

public interface AgenticHarness extends AutoCloseable
One conversation with a model: a system prompt, a tool set, and the accumulated message history that send(String) appends to. Obtain one from AiContext.newAgenticHarness(String, String, Agent.AgentFactory), and close it when the owner that built it goes away.

A harness is owned, not shared: the context that minted it holds a strong reference until close() runs, so exactly one owner must have exactly one deterministic close point. Short-lived callers should use try-with-resources; long-lived owners should close in the teardown hook that matches their construction site, and close the outgoing harness before replacing it.

try (AgenticHarness harness = aiContext.newAgenticHarness(model, MyAgent::new)
    .label("Nightly report")
    .build()) {
  return harness.send("Summarize today's alarms.");
}

send(String) is not safe to call concurrently on the same harness; drive one turn at a time.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Clear all conversation history except the system prompt, returning the harness to the state it was in immediately after construction.
    void
    Release this harness and drop it from its context's active list.
    Stable identity for this conversation, minted at construction and constant for the life of the harness.
    void
    rewind(int turns)
    Discard the most recent turns turns from conversation memory, so a subsequent send(String) proceeds as if those turns never happened.
    send(String userMessage)
    Send a user message and return the model's final text reply, after dispatching any tool calls the model makes along the way.
    <T> T
    send(String userMessage, Class<T> resultType)
    Send a user message and return the model's reply parsed into resultType.
  • Method Details

    • getId

      UUID getId()
      Stable identity for this conversation, minted at construction and constant for the life of the harness. Survives clearMemory(). Matches the HarnessInfo.id() this harness is listed under in its context's harness registry.
    • send

      String send(String userMessage) throws UpstreamModelProviderException
      Send a user message and return the model's final text reply, after dispatching any tool calls the model makes along the way. This message and the resulting reply are added to the conversation so later calls to send see them.
      Parameters:
      userMessage - the user's message to send to the model.
      Returns:
      the text of the model's final reply.
      Throws:
      UpstreamModelProviderException - when the underlying provider call fails (HTTP error, auth, rate limit, timeout, unreachable base URL, etc.).
      RuntimeException - if the model keeps requesting tool calls past the iteration cap; it is not a provider failure.
    • send

      <T> T send(String userMessage, Class<T> resultType) throws UpstreamModelProviderException
      Send a user message and return the model's reply parsed into resultType. Participates in the running conversation: the user message is appended to memory before the request, and the parsed reply (along with any tool calls the model makes along the way) is appended after.

      resultType must be a Jackson-decodable type — typically a record or POJO whose fields are themselves Jackson-decodable. Fields are optional by default; use @JsonProperty(required = true) to reject a reply that omits one. Generic collection types (e.g. List<X>) cannot be expressed through a Class<T> token; wrap them in a record (e.g. record AlarmList(List<AlarmConfig> alarms) {}) and request the wrapper.

      Describing the shape to the model is the caller's job. No schema is sent to the provider, so put the reply contract in the agent's system prompt or the harness's system-prompt addendum. A reply that does not decode goes back to the model once, carrying the decoder's own complaint; a second failure ends the turn.

      Parameters:
      userMessage - the user's message to send to the model.
      resultType - the Jackson-decodable target type for the model's reply.
      Returns:
      the parsed reply.
      Throws:
      UpstreamModelProviderException - when the underlying provider call fails (HTTP error, auth, rate limit, timeout, unreachable base URL, etc.) — no reply was produced.
      TypedOutputParseException - when the model replied but the reply doesn't decode into resultType — providers vary in how strictly they honor a response-format schema. Unchecked.
      UnsupportedOperationException - if this harness does not support structured outputs.
    • clearMemory

      void clearMemory()
      Clear all conversation history except the system prompt, returning the harness to the state it was in immediately after construction. Use this for a UI "Start new chat" / "Clear conversation" action.

      Must not be called concurrently with send(String).

      Throws:
      IllegalStateException - if this harness is closed.
    • rewind

      void rewind(int turns)
      Discard the most recent turns turns from conversation memory, so a subsequent send(String) proceeds as if those turns never happened. A turn is one user message together with everything the model produced in response to it (assistant replies, tool requests, and tool results). Use this to back a UI "retry" that must roll conversation state back before re-sending a prompt, rather than re-sending on top of the previous reply.

      rewind(0) is a no-op, as is a rewind before any send(String) has run. Rewinding past the start of available history discards all conversation messages. The system prompt is unaffected either way; it is re-provided on the next send.

      Must not be called concurrently with send(String).

      Parameters:
      turns - the number of most-recent turns to discard; 0 does nothing.
      Throws:
      IllegalArgumentException - if turns is negative.
      IllegalStateException - if this harness is closed.
    • close

      void close()
      Release this harness and drop it from its context's active list. Idempotent.

      Required. The context holds a strong reference to every harness it mints until this method is called, so a harness that is never closed is never collected — along with everything its event consumer and tools reach, which for a hosted harness is typically the host component or panel. Close every harness at the owner's teardown point, and close the outgoing harness before replacing it.

      In-flight send(String) calls are not interrupted; they run to completion. Any subsequent send, clearMemory(), or rewind(int) throws IllegalStateException: a closed harness accepts no new work and mutating its memory would be unobservable. Callers that may race a close against queued work should check their own disposed/cancelled state before driving the harness rather than catching this.

      Specified by:
      close in interface AutoCloseable