Use LLM Access Inside a Hermes Plugin

Use the host-owned ctx.llm surface for bounded plugin-side model calls without duplicating provider credentials or bypassing operator trust controls. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

ctx.llm is for a plugin task that needs one model call outside the main agent conversation: summarization, translation, classification, structured extraction, or a small pre-filter.

The host owns provider resolution, credentials, fallback, timeout plumbing, and audit attribution. Plugins provide messages or structured instructions and validate the result they need.

Use free-form completion for text and structured completion for typed data. Async equivalents support gateway adapters and hooks. A purpose string improves auditability.

Provider, model, agent, and profile overrides are independently trust-gated. A plugin follows the user’s active provider by default and cannot silently seize a different credential path.

Practical checklist

Use the smallest prompt and token budget that solves the plugin task.
Prefer structured output when downstream code makes decisions.
Handle parsed is None and preserve a safe fallback.
Add a meaningful audit purpose for recurring calls.
Request override permissions only when the plugin truly needs them.

Common pitfalls

Calling provider SDKs directly and duplicating secret handling.
Treating model output as trusted because it matched JSON syntax.
Assuming model override permission also grants provider override.
Using an out-of-band plugin call when the work should be a visible agent tool or lifecycle hook.

Verification steps

Test free-form and structured lanes with deterministic fixtures.
Inspect provider/model/usage/audit fields without logging credentials.
Exercise malformed structured output and trust-denied overrides.
Confirm the plugin follows a normal host model change when no override is requested.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/plugin-llm-access