Skip to main content

LLM Helper

The llm helper runs a single, synchronous LLM completion from inside your script — extract fields from messy text, classify an input, draft a reply — and returns the result as a JSON string. Metering and model access are handled by the platform; there are no keys to manage.

llm.invoke​

  • Name
    llm.invoke
    Type
    (systemPrompt: string, userPrompt: string) => string
    Description

    Runs one completion. systemPrompt sets behavior and output format (pass "" to skip it); userPrompt is the user-turn content. Blocks until the model responds, up to 120 seconds.

  • Name
    llm.invoke
    Type
    (systemPrompt: string, userPrompt: string, maxTokens: number) => string
    Description

    Same, with an explicit cap on completion tokens. Values of 0 or less are ignored (the model default applies).

The model is chosen by the platform: scripts run against Autessa's small instruction-following tier — fast and inexpensive, suited to extraction, classification, and short rewrites rather than long-form reasoning. Model and temperature are not configurable from the script. For heavyweight generation, use a dedicated LLM_CALL tool and chain it via tools.invokeById.

Return format​

Always a JSON string — JSON.parse it and check success:

{
  "success": true,
  "id": "chatcmpl-abc123",
  "content": "{\"sentiment\": \"positive\", \"topics\": [\"billing\"]}",
  "usage": {
    "promptTokens": 184,
    "completionTokens": 31,
    "totalTokens": 215
  }
}
  • Name
    success
    Type
    boolean
    Description

    true when the completion succeeded.

  • Name
    id
    Type
    string
    Description

    Provider-side completion id.

  • Name
    content
    Type
    string
    Description

    The model's text output. If you asked for JSON, parse this string as a second step.

  • Name
    usage
    Type
    object, optional
    Description

    promptTokens, completionTokens, totalTokens when the provider reports usage.

On failure the envelope is { "success": false, "errorCode": "...", "errorMessage": "..." } with errorCode one of:

  • Name
    CLIENT_NOT_AVAILABLE
    Type
    errorCode
    Description

    The LLM client wasn't initialized in this environment.

  • Name
    INVOCATION_ERROR
    Type
    errorCode
    Description

    The call failed or timed out (120-second limit); errorMessage carries the cause.

Prompt tips​

  • Pin the output format in the system prompt. "Respond with only a JSON object, no prose, no code fences" makes the double-parse pattern below reliable.
  • Keep it single-shot. There is no conversation state between invoke calls; include everything the model needs in each call.
  • Set maxTokens for classification tasks. A tight cap keeps latency and cost down when you only need a word or a small object.
  • Expect occasional format drift. Wrap the inner JSON.parse in a try/catch and fall back gracefully.

Example: extract, then use​

const ticket = variables.get("ticketBody");

const raw = llm.invoke(
  "You extract structured data from support tickets. " +
  "Respond with only a JSON object: {\"sentiment\": \"positive|neutral|negative\", " +
  "\"product\": string, \"needsHuman\": boolean}. No prose, no code fences.",
  ticket,
  200
);

const result = JSON.parse(raw);
if (!result.success) {
  response.setResponse(JSON.stringify({ error: result.errorCode + ": " + result.errorMessage }));
} else {
  let extracted;
  try {
    extracted = JSON.parse(result.content);        // parse the model's JSON
  } catch (e) {
    extracted = { sentiment: "neutral", product: "unknown", needsHuman: true };
    console.warn("model returned non-JSON, using fallback:", result.content);
  }
  console.log("tokens used:", result.usage ? result.usage.totalTokens : "n/a");
  response.setResponse(JSON.stringify(extracted));
}

llm.invoke returns a JSON envelope string, and content inside it is another string. Getting to your extracted object takes two parses — the same double-parse pattern as the API helper.