Skip to content
AI

Calling AI from AmiScript

session.promptAi(...) invokes the configured AI provider from inside AmiScript on the Web, such as a callback. It is a single-turn completion with no tools: you hand it a prompt (and optionally some data), and the script resumes with the model's response as a plain string.

Use it to run a fixed instruction over live, filtered data without leaving your Layout logic. Typical uses are classifying rows, summarizing a result set, and extracting structured fields.

Prerequisites

session.promptAi uses the same providers as the chatbot. AI must be enabled and at least one provider configured on the Web component (see Ask AI Chatbot -> Enabling and Configuring Providers). If AI is disabled, the call returns null.

Signature

1
String promptAi(String provider, String model, Map options, List data, String prompt)
Parameter Type Meaning
provider String Provider id ("anthropic", "openai", …). Null or blank uses the configured default provider.
model String Model id. Null or blank uses that provider's default model.
options Map Optional. "system" (system-prompt string), "max_tokens" (Integer), "max_chars" (overall prompt character cap; non-positive disables it). May be null.
data List Optional. Each element (Tables, TableSets, collections, maps, scalars) is serialized to JSON and appended to the prompt. May be null.
prompt String The instruction text.

Returns the provider's response text, or null when AI is disabled, the provider returns nothing usable, or the call fails.

Behavior and Constraints

  • Deferred and single-turn. The script pauses at the call and resumes with the response, without holding the Session while the provider answers. It does not run the agentic loop and calls no tools: it is a plain completion.
  • The API key is never passed in script. It is resolved server-side from ami.web.ai.<provider>.api_key.
  • Bounded by the script's own timeout. The call (including the provider socket read) is governed by the executing callback's timeout. If you expect a long response, raise that callback's timeout accordingly.
  • Prompt size is capped. The assembled prompt (instruction plus serialized data) is truncated to a default character limit; override with options.max_chars, or pass a non-positive value to disable the cap.
  • Logged to AmiAi.log as prompt_ai_call / prompt_ai_result (or prompt_ai_disabled), so scripted AI use is auditable alongside chatbot activity.

Examples

Summarize a filtered set of alert rows in a callback, using the default provider and model:

1
2
3
4
5
6
7
8
9
// 'alerts' is a table/result available in this scope
Map options = {"system": "You are a trading-risk analyst. Be concise.", "max_tokens": 500};
List data = [alerts];
String summary = session.promptAi(null, null, options, data,
    "Summarize the top risks in the attached alert rows in three bullet points.");

if (summary != null) {
    session.log(summary);
}

To pin a specific provider and model, pass them explicitly:

1
2
String label = session.promptAi("anthropic", "claude-opus-4-8", null, [row],
    "Classify this instrument as EQUITY, BOND, or DERIVATIVE. Answer with one word.");

Warning

A null return means "AI unavailable or the call failed." Always guard the result before using it, so a Layout still functions when AI is disabled or a provider is unreachable.