Free instruction (AI)

Gives the model a free-form instruction about the email and the working data. The node produces text or JSON: it sends nothing and changes nothing — add an action node downstream to act.

Free instruction (AI) is the general-purpose AI node: you write what the model should do, and it answers with text or with a JSON object you describe. Use it for whatever the dedicated nodes do not cover: rewriting a text, judging the urgency of a request, turning a list into a table, comparing two values.

The node only produces data. It sends nothing, changes nothing and triggers nothing, and its instructions tell the model never to claim it acted. To act on the answer, link an action node downstream: Compose then Send, a table write, a Notify. For the common cases, prefer the dedicated nodes: Categorize, Extract, Summarize, Compose (AI).

At a glance

• Type: ai.prompt · version 1
• Category: AI
• Kind: Step — one stage of a run
• Effect: No external effect (none) — nothing is written outside Mankomail; safe to replay
• Needs a carrier email: No
• Connection: None
• Inputs: main
• Outputs: main
• Service ports: model (llm.model, optional)

Parameters

prompt

Instruction — What the model should do. Accepts {{ }} expressions: {{ email.subject }}, {{ data.extract_1.amount }}. The email content is provided separately, as delimited data.

• Type: Long text (text)
• Required: Yes
• Default: "" (empty)
• 10000 characters at most
• Expressions: {{ }} accepted

outputFormat

Output format

• Type: One choice (options)
• Required: Yes
• Default: text
• Options:
  • text — Text: The model text in text.
  • json — Structured JSON: An object matching the schema, in json.

jsonSchemaText

JSON schema — An object JSON Schema: { "type": "object", "properties": { "urgency": { "type": "string" } } }.

• Type: Long text (text)
• Required: Yes
• Default: "" (empty)
• 20000 characters at most
• Shown when: outputFormat is json
• Expressions: {{ }} not accepted

Outputs

• main

Data produced

What this node adds to the run data, and how to read it in an expression. <step> stands for the step key: the node name turned into an identifier (see Data and expressions).

• {{ data.<step>.text }} — string. Written when Output format is Text: the model answer, trimmed.
• {{ data.<step>.json.<property> }} — object. Written when Output format is Structured JSON: the object returned by the model, shaped by your JSON schema. Read each property by its name.
• {{ data.<step>.simulated }} — boolean. true when the output was fabricated instead of coming from a model (test run on an instance with no usable AI provider). false for a real model answer.

Example

A support team wants an urgency score on every request. Add a Free instruction (AI) node named Urgency:

prompt: "Rate how urgent this request is for our support team, and say why in one sentence."
outputFormat: json
jsonSchemaText: |
  {
    "type": "object",
    "properties": {
      "level": { "type": "string", "enum": ["low", "normal", "high"] },
      "reason": { "type": "string" }
    },
    "required": ["level", "reason"]
  }

The step data reads:

{
  "json": { "level": "high", "reason": "The customer's production site is down." },
  "simulated": false
}

A Switch on {{ data.urgency.json.level }} then routes high-urgency requests to the on-call team.

Text or JSON

• Text: the answer lands in text. The model is told to answer in plain text without markup, and to write in the language of the incoming email, whatever the language of your instruction.
• Structured JSON: the answer lands in json. The JSON schema field must describe an object ("type": "object"), with typed properties (string, number, integer, boolean, object, array, null) and an optional required list. It is a simple subset of JSON Schema, not the full specification. The schema is checked as you type: an invalid schema is shown under the field and the workflow cannot be published with it. The JSON schema field is not templatable, so the keys of json stay predictable downstream.

What the model sees

Your Instruction is sent as is, after {{ }} expressions are rendered. When the run has a triggering email, its subject and text body are added in a separate, delimited block, with an explicit instruction to treat it as data and ignore any instruction it contains. When the run has no email (schedule, webhook), the model only receives your instruction.

How the model is chosen

The node has a model service port. Leave it empty and the call uses the default model the administrator set for the General use on the Connections page (Artificial intelligence section) (or the instance default). Link a provider node such as Anthropic (Claude) or OpenAI-compatible API to the model port to run this node on that provider.

Tips

• Inserted values are data. If your instruction inserts third-party content ({{ email.subject }}, {{ data.<step>.attachments.0.text }}), that content reaches the model inside the user message, never the system message, and the model is told that inserted values are data, not instructions. Prefer the delimited email block when you can: it is the stronger protection.
• The node cannot act. An answer saying "I have sent the email" is fiction. Only action nodes have effects, and only they are held back in a test run or by the send kill switch.
• Test runs. In test runs the model is really called. If the instance has no usable AI provider, the output is fabricated (a fixed text, or placeholder values matching your schema), simulated is true and the run detail says the AI was skipped.
• Errors. An empty instruction gives node_nothing_to_do; an invalid schema at run time gives node_invalid_param. In JSON mode, an answer that is not a JSON object gives llm_invalid_output, which is retried. See Error handling.