Package com.inductiveautomation.ignition.common.ai
GatewayAiContext,
DesignerAiContext) that extends AiContext.
Code that only needs to ask a model a question should depend on this package and nothing else.
The three roles
Agent is configuration — a system
prompt, a set of CallableTools, and optional
supplemental context. Agents are stateless recipes, built fresh per harness through an Agent.AgentFactory.
AgenticHarness is one conversation.
It pairs an agent with a specific model, accumulates message history across send calls,
and runs the tool-calling loop. Two harnesses built from the same agent share no memory.
AiContext is the factory and
registry. It resolves provider/model names against the scope's catalog, mints harnesses
through AiContext.HarnessBuilder, and tracks
every harness it minted.
Harness lifecycle and ownership
A harness has exactly one owner: whoever called build(). Ownership carries a close
obligation, and it is not advisory. The context holds each harness it mints by strong
reference so that its registry of live harnesses can be authoritative — an entry there is a live
harness, not a guess. The only thing that removes an entry is AgenticHarness.close().
The consequence is direct: a harness that is never closed is never collected, and neither is anything it reaches. That is more than the conversation buffer. A harness's event consumer and per-host tools typically capture the UI or component that built it, so a missed close on a hosted harness pins a Perspective component model and its session, or a Swing panel and its whole hierarchy.
Two shapes cover every case:
- One-shot — a route, a script call, a single
send. Use try-with-resources. - Long-lived — a harness parked in a field for the life of a component, panel, or session. Close it in the teardown hook that matches the construction site, and close the outgoing harness before assigning a replacement. Rebuild-on-config-change is the most common leak: the owner survives, so nothing else will ever close the harness it just discarded.
close() is idempotent and does not interrupt an in-flight send; cancel your
own work first if you need the turn to stop. A send after close throws IllegalStateException.
Transcripts
Every harness writes a JSONL transcript of its conversation, and the harness owns that
file: it opens one when it is built and closes it as part of close(). The owning
AiContext decides where transcripts land and how many are kept — on the gateway, under
the logs directory; in the Designer, under the user's home. A caller's only say in the matter is
AiContext.HarnessBuilder.transcript(com.inductiveautomation.ignition.common.ai.TranscriptPolicy), which opts one harness out. There
is no writer to hold, pass, or close, and a transcript that cannot be written never fails a turn.
Observing a running conversation
Two channels, aimed at different consumers. HarnessEvent is a push stream delivered synchronously
on the thread driving the turn — turn boundaries, tool calls, reasoning traces, token spend. UI
consumers attach one via HarnessBuilder.events(...) and marshal to their own event
thread. HarnessInfo is the pull side: an
immutable snapshot with identity, model, timestamps, and cumulative counters, read from the
owning context's harness registry — a scope-internal surface, not part of this SPI, whose gateway
consumer is the AI sessions page. Snapshots deliberately carry no handle on the harness, so a
status page can enumerate AI activity without being able to drive a conversation it does not own.
Errors
Provider-side failures — auth, rate limits, timeouts, unreachable endpoints — arrive as UpstreamModelProviderException, a checked exception
with a reason() that keeps the provider's own failure as its cause. Anything else
propagating out of send came from a tool or from the caller's own code.
Extension guidance
Types here must be usable from gateway, Designer, and client scopes, which rules out any
dependency on scope-specific context objects or on the AI module's own classes. Scope-specific
capability belongs on the facade interface for that scope; implementation belongs in the AI
module. This SPI is implemented outside the platform, so treat additions to AiContext and
AgenticHarness as breaking changes.
-
ClassDescriptionA single contribution to an
Agent's additional context.Configures an AI agent: its system prompt, the tools it can call, and any supplemental context that shape its behavior.ConstructsAgentinstances.One conversation with a model: a system prompt, a tool set, and the accumulated message history thatAgenticHarness.send(String)appends to.Who the user is that triggered an AI run.Platform-visible builder returned byAiContext.newAgenticHarness(String, String, Agent.AgentFactory).A specific model from a specific provider.A tool exposed to the model: pairs a declarativeToolDescription(sent to the model so it knows how to call the tool) with anCallableTool.invoke(Map)method that executes the call with parsed arguments.Agentcomposed from named slots — a preamble and framing for the system prompt, a series ofToolBundles, and a series ofAdditionalContextParts.Builder forComposedAgent.A heading and body pair contributed to anAgent's additional context.Event emitted by the agentic harness at the natural boundaries of its tool-calling loop.Emitted when the model returns prose alongside the tool calls it is requesting.Emitted when the model's response includes a reasoning trace.Emitted when a typedAgenticHarness.send(String, Class)rejected a reply and asked again.Emitted when a chat response stopped because it hit the model's output-token limit (finish reasonLENGTH); its final text, or a tool call's arguments, may be cut off.Emitted when the sub-harness opened byHarnessEvent.SubagentStartedreturns, carrying its final response (or error message) so consumers can close out the subagent scope.Emitted byspawn_subagentimmediately before its sub-harness starts running, so downstream consumers can scope subsequent events to the subagent.Emitted after a chat response that reports token usage, carrying the input and output tokens billed for that one call.Emitted after a tool invocation completes successfully.Emitted when a tool invocation throws.Emitted when the model requests a tool invocation, before the tool runs.Emitted when the conversation turn opened byHarnessEvent.TurnStartedcompletes, carrying the model's final text reply.Emitted at the start of each conversation turn, immediately after the user's message has been accepted but before the first request is sent to the model.Emitted at most once after eachHarnessEvent.TurnFinished, reporting how full the orchestrator's conversation is as of the request that produced the final reply.Immutable snapshot of oneAgenticHarnessas of the moment its context's harness registry was read.Lifecycle state at the moment the snapshot was taken.Source of MCP-derivedCallableTools for anAgenticHarness.Ignition-side mirror of langchain4j'sdev.langchain4j.model.chat.Capability.Describes a single model offered by a provider.Describes an AI model provider.Thrown when a model provider's configuration cannot produce usable credentials — a missing or blank API-key environment variable, or aSecretConfigthat resolves to nothing.Turns a model's reply text into the type a typedAgenticHarness.send(String, Class)asked for.A named slot in anAgent's system prompt.Marks a method as a tool callable by an AI model.A group ofCallableTools contributed to anAgentas a unit.Declarative metadata for a tool: how it's identified to the model.Describes a parameter of aTool-annotated method.Helpers for buildingCallableTools.Whether a harness writes a conversation transcript.Thrown byAgenticHarness.send(String, Class)when the turn itself succeeded but the model's final reply could not be decoded into the requested type.A model-provider call failed for a provider-side reason.Host-supplied surface for pausing the agent's tool-dispatch loop to consult the user.