Skip to content
LainstackDocs

AI Prompt

Runs an AI prompt with structured runtime parameters.

@lainstack/ai/prompt · AI

How to use it

Section titled “How to use it”

Makes one model call with a system prompt and a user prompt, and returns the reply. Use it to summarize, rewrite or extract from text. For one label out of a fixed list, use @lainstack/ai/classify. For multi-step work with tools, use @lainstack/ai/agent.

  • Both prompts are resolved before the block runs. Insert upstream values as references (references); the block does not render templates.
  • Needs a workspace AI connection in credentialId. model must be a model of that connection.
  • Typed outputs are text, model, responseFormat, promptHash and usage. With responseFormat json the reply is parsed into a json field, but json is not a declared output leaf, so later blocks cannot reference fields inside it. Reference text and parse it with @lainstack/data/parse-json, or use @lainstack/ai/agent with a JSON answer shape when you need typed fields.
  • A reply that is not valid JSON fails the block (provider_response_invalid) when responseFormat is json.
  • The timeout defaults to 30 s (allowed 1 s to 300 s).
  • mcpEnabled lets the model call tools of the connections listed in mcpConnectionRefs (at least one, at most 16). Calls are capped by mcpToolPolicy.maxToolCalls (default 4, at most 24) and by the lowest limit of those connections. Tool calls act on real systems.
  • Model output is not deterministic. A replay or a test run calls the model again, unless the block has a pinned sample output (testing).

Settings

Section titled “Settings”
Setting Key Type Details
Connection (required) credentialId Connection Workspace AI connection used for this prompt.
Model (required) model Text Model identifier configured for the selected AI connection.
System prompt (required) systemPromptTemplate Text Instructions that define the assistant role and constraints.
User prompt (required) userPromptTemplate Text The request sent to the model for each run.
Response format responseFormat One of Text, JSON Expected response format. Defaults to text.
Maximum output tokens maxOutputTokens Number Optional upper bound for provider output tokens.
Thinking effort reasoningEffort Text Optional reasoning effort supported by the selected model. At most 32 characters.
Temperature temperature Number Sampling temperature between 0 and 2.
Top P topP Number Nucleus sampling probability between 0 and 1.
Timeout timeoutMs Number Maximum provider request duration in milliseconds.
Enable tools mcpEnabled Yes or no Allow the prompt to call configured MCP tools.
Tool connections mcpConnectionRefs Connections MCP connections available to this block run. At most 16 items.
Maximum tool calls mcpToolPolicy.maxToolCalls Number Upper bound for MCP tool calls during one prompt run.
Parallel tool calls mcpToolPolicy.allowParallelTools Yes or no Allow multiple MCP tool calls to run in parallel when the provider requests it.
Tool transcript field mcpTranscriptOutputKey Text Optional output field containing the sanitized MCP transcript. At most 120 characters.

Outputs

Section titled “Outputs”
Output Path Type
Model model Text
Response Format responseFormat Text
Text text Text
Prompt Hash promptHash Text
Usage usage Record