Interface AgenticHarness
- All Superinterfaces:
AutoCloseable
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 TypeMethodDescriptionvoidClear all conversation history except the system prompt, returning the harness to the state it was in immediately after construction.voidclose()Release this harness and drop it from its context's active list.getId()Stable identity for this conversation, minted at construction and constant for the life of the harness.voidrewind(int turns) Discard the most recentturnsturns from conversation memory, so a subsequentsend(String)proceeds as if those turns never happened.Send a user message and return the model's final text reply, after dispatching any tool calls the model makes along the way.<T> TSend a user message and return the model's reply parsed intoresultType.
-
Method Details
-
getId
UUID getId()Stable identity for this conversation, minted at construction and constant for the life of the harness. SurvivesclearMemory(). Matches theHarnessInfo.id()this harness is listed under in its context's harness registry. -
send
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 tosendsee 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
Send a user message and return the model's reply parsed intoresultType. 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.resultTypemust 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 aClass<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 intoresultType— 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 isclosed.
-
rewind
void rewind(int turns) Discard the most recentturnsturns from conversation memory, so a subsequentsend(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 anysend(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 nextsend.Must not be called concurrently with
send(String).- Parameters:
turns- the number of most-recent turns to discard;0does nothing.- Throws:
IllegalArgumentException- ifturnsis negative.IllegalStateException- if this harness isclosed.
-
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 subsequentsend,clearMemory(), orrewind(int)throwsIllegalStateException: 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:
closein interfaceAutoCloseable
-