LLMAgent

Controlled Model Mediation

Higher-level components in AchillesAgentLib are not expected to talk directly to providers. That work is concentrated in LLMAgent so that prompt execution, memory shaping, output coercion, and call logging remain consistent across the rest of the runtime. The architectural value of this class is therefore not only convenience. It is that it prevents every subsystem from inventing its own model-calling conventions.

This becomes especially important once the same runtime must support plain completions, structured JSON extraction, code-oriented responses, confirmation resolution, intent detection, and long-lived sessions. In a looser architecture, each of these concerns would drift into local conventions. In AchillesAgentLib they are pulled into one shared mediation surface. RecursiveSkilledAgent and the skill subsystems then build on that common layer rather than bypassing it. The role of RecursiveSkilledAgent as the top-level coordinator is described separately in RecursiveSkilledAgent.

The practical result is that LLMAgent sits between the rest of the runtime and the underlying invoker strategy. It does not remove the probabilistic nature of the model, but it does make the path to that model more explicit, more inspectable, and easier to keep stable.

Prompt Execution, Interpretation, and Sessions

The lowest direct method is complete(). It expects a prompt string and optional history, tier, model, tags, and context, forwards those values to the configured invoker strategy, records input and output character counts, logs per-call telemetry, and returns the provider output as a string. This is the most direct general-purpose surface offered by the class.

executePrompt() builds on that lower layer. It can prepend memory segments such as global, user, session, or skill short memory to the prompt context and then routes the request through the task-execution helper. When responseShape is declared, it also performs bounded post-processing on the returned text. For json, it extracts JSON and throws if parsing fails. For code, it strips code fences. For json-code, it extracts a JSON object and requires that the object contain a code field. The method therefore does not “understand” arbitrary schemas, but it does centralize the output-coercion patterns used by the rest of the runtime.

const result = await llmAgent.executePrompt('Summarize the report', {
    tier: 'fast',
    responseShape: 'json',
    context: { intent: 'summarize-report' },
    sessionMemory,
});

Alongside prompt execution, LLMAgent also exposes a small set of interpretation helpers. interpretMessage() converts free-form user replies into constrained outcomes such as accept, cancel, update, or idea-like payloads, using heuristics first and the model second. resolveConfirmation() resolves ambiguous yes-or-no language into yes, no, or unclear together with a confidence value. detectIntents() classifies a request against a described skill space and requires a JSON result. These methods are important because they allow natural language to be turned into bounded operational signals rather than leaving every caller to parse conversational text independently.

The third major responsibility is session creation. startLoopAgentSession() creates a loop-based session over a tools object and immediately starts it with the initial prompt. startSOPLangAgentSession() creates an SOP-based session over a skills description object and likewise starts it immediately, with optional planOnly behavior. The detailed behavior of those session types is documented on Agentic Sessions, but their common entry point is LLMAgent.

const loopSession = await llmAgent.startLoopAgentSession(tools, 'Start the workflow');

const sopSession = await llmAgent.startSOPLangAgentSession(skillsDescription, 'Run the plan', {
    planOnly: false,
});

Two additional operational details complete the picture. First, cancel() forwards cancellation to the underlying request layer and attempts to close active processing callbacks. Second, getCallLog() returns the per-call telemetry accumulated by the agent, including input size, output size, model, tier, duration, and intent. This makes LLMAgent not only a prompt wrapper, but the general LLM-facing runtime service on top of which the rest of the library is built.