AI | Boomerang Flow

The AI category has 2 tasks. Each entry shows the task's latest revision, the one the palette adds. See Reading an entry.

AI Agent

A tool-calling loop against an OpenAI-compatible model: the model calls declared or MCP tools until it gives a final answer, optionally held to a JSON Schema.

Slug: ai-agent
Type: ai
Revision: 2
Image: boomerangio/task-ai:2.1.0

Parameters

Label	Name	Type	Required	Default	Helper text
Model	`model`	Text	Yes		The model identifier the endpoint expects, for example openai/gpt-4o-mini.
Prompt	`prompt`	Text Editor - Text	No		The user message. Supports $(params.x) and $(tasks.x.results.y) references. Give this or Prompt file, unless Messages or Messages file replaces both.
Prompt file	`promptFile`	Text	No		A path on the run workspace whose contents are the user message, for a prompt too large for a param. Give Prompt or Prompt file, not both: neither fails with MISSING_PARAM, both with INVALID_PARAM.
System prompt	`systemPrompt`	Text Editor - Text	No		Sent as the system message ahead of the prompt. Ignored when Messages is given.
Messages	`messages`	`json`	No		A JSON array of {role, content} sent as the exact message array, replacing System prompt and Prompt. For replays and evals. Fails with INVALID_PARAM when it does not parse. Give this or Messages file, not both.
Messages file	`messagesFile`	Text	No		A path on the run workspace holding the JSON array of {role, content}, for a message array too large for a param. Give Messages or Messages file, not both; either replaces System prompt and Prompt.
Endpoint	`endpoint`	Text	No		An OpenAI-compatible base URL - OpenRouter, LiteLLM, Azure AI Foundry or Ollama. When absent the executor's default applies: the dispatcher's environment (OPENAI_BASE_URL) for a container run, the embedding product's gateway settings in-process.
API token	`token`	Secured	No		Bearer token for the endpoint. Blanked on every workspace-scoped read. When absent the executor's default applies: the dispatcher's environment (OPENAI_API_KEY) for a container run, the embedding product's gateway settings in-process.
Temperature	`temperature`	Slider	No		Sampling temperature. Lower is more deterministic. Blank sends none, so the provider's default applies; newer reasoning models reject any other value.
Max tokens	`maxTokens`	Number	No		Upper bound on the tokens the model may generate, sent as max_tokens. Blank sends none, so the provider's default applies; a max_completion_tokens key in Request parameters replaces it.
Seed	`seed`	Number	No		Optional sampling seed, for endpoints that honour one.
Request parameters	`parameters`	`json`	No		A JSON object merged into the request as sent: top_p, reasoning_effort, verbosity, max_completion_tokens, frequency_penalty, presence_penalty and so on. A key here wins over Temperature, Max tokens and Seed. Fails with INVALID_PARAM when it does not parse.
Response format	`responseFormat`	Select	No	`text`	Ask the model for free text or a JSON object.
JSON Schema	`jsonSchema`	Text Editor - Text	No		A JSON Schema object. With Response format json, the reply is held to it (response_format json_schema, strict) and validated before it is returned.
Files	`files`	Text	No		Comma-separated paths on the run workspace, read into the prompt context. Appended to the last user message's text, or to its last text part when it has content parts.
Max context bytes	`maxContextBytes`	Number	No	`65536`	Byte budget for the files read into context. Reading stops at the budget.
Images	`images`	Text	No		Images to send with the prompt, comma-separated: paths on the run workspace (PNG, JPEG, GIF or WEBP, read and sent inline) or https URLs (fetched by the provider). Attached to the last user message after its text. Needs a vision-capable model. This is a text param, so a presigned URL is stored and shown with the run; put private images on the workspace instead. The agent resends the images on every turn, since they stay in the conversation, so each turn pays for them again.
Image detail	`imageDetail`	Select	No		How closely the provider looks at each image. Blank sends nothing, so the provider's default applies. Applies to Images only, not to image parts inside Messages.
Max image bytes	`maxImageBytes`	Number	No	`5242880`	Largest workspace image to send, in bytes. A larger file fails with FILE_TOO_LARGE rather than being resized or skipped. Not sent to the provider, and URLs are not checked.
Output file	`outputFile`	Text	No		A path on the run workspace to write the full reply to, for a following uploadartifact node. The output result still carries the reply up to the results cap.
Tools	`tools`	`json`	No		A JSON array of {name, description, inputSchema} tools the executor implements natively. A container run cannot resolve these and fails with UNKNOWN_TOOL before the first call unless each name is served by an MCP server below.
MCP servers	`mcpServers`	`json`	No		A JSON array of {name, url} MCP servers whose tools the agent may call. Never put a credential here: a token comes from MCP tokens below, keyed by server name, or from the executor's default for that name.
MCP tokens	`mcpTokens`	Secured	No		A JSON object of {serverName: bearerToken} for the MCP servers above. Password-typed, so it is blanked on read and never logged.
Allowed tools	`allowedTools`	`json`	No		A JSON array of tool names the model may call. Blank allows every tool declared above.
Tool context	`toolContext`	`json`	No		A JSON object of opaque values handed to executor tools on every call and never shown to the model.
Max turns	`maxTurns`	Number	No	`10`	Model calls before the loop stops with MAX_TURNS_EXCEEDED.
Max tool calls	`maxToolCalls`	Number	No		Tool calls in total before the loop stops with MAX_TURNS_EXCEEDED. Blank is no limit beyond Max turns.
Parallel tool calls	`parallelToolCalls`	Boolean	No	`true`	Let the model request several tool calls in one turn.
Tool result reinforcement	`toolResultReinforcement`	Text Editor - Text	No		Appended as a user message after the tool results on every turn, to keep the model on task.

Results

Name	Description
`output`	The model's reply: the text, or the JSON string when Response format is json
`finishReason`	Why the model stopped, as the endpoint reported it
`model`	The model the endpoint actually served
`promptTokens`	Tokens consumed by the prompt
`completionTokens`	Tokens generated in the reply
`totalTokens`	Prompt plus completion tokens, the value a platform sums to meter usage
`reasoningTokens`	Reasoning tokens, when the endpoint reports them; empty otherwise
`cachedPromptTokens`	Prompt tokens served from the provider's cache, when reported; empty otherwise
`cost`	The call's cost as the endpoint reports it (OpenRouter usage.cost); empty otherwise
`turns`	Model calls made
`toolCalls`	Tool calls made across all turns

AI Prompt

One call to an OpenAI-compatible model: a prompt or an exact message array in, the reply out, optionally held to a JSON Schema.

Slug: ai-prompt
Type: ai
Revision: 2
Image: boomerangio/task-ai:2.1.0

Parameters

Label	Name	Type	Required	Default	Helper text
Model	`model`	Text	Yes		The model identifier the endpoint expects, for example openai/gpt-4o-mini.
Prompt	`prompt`	Text Editor - Text	No		The user message. Supports $(params.x) and $(tasks.x.results.y) references. Give this or Prompt file, unless Messages or Messages file replaces both.
Prompt file	`promptFile`	Text	No		A path on the run workspace whose contents are the user message, for a prompt too large for a param. Give Prompt or Prompt file, not both: neither fails with MISSING_PARAM, both with INVALID_PARAM.
System prompt	`systemPrompt`	Text Editor - Text	No		Sent as the system message ahead of the prompt. Ignored when Messages is given.
Messages	`messages`	`json`	No		A JSON array of {role, content} sent as the exact message array, replacing System prompt and Prompt. For replays and evals. Fails with INVALID_PARAM when it does not parse. Give this or Messages file, not both.
Messages file	`messagesFile`	Text	No		A path on the run workspace holding the JSON array of {role, content}, for a message array too large for a param. Give Messages or Messages file, not both; either replaces System prompt and Prompt.
Endpoint	`endpoint`	Text	No		An OpenAI-compatible base URL - OpenRouter, LiteLLM, Azure AI Foundry or Ollama. When absent the executor's default applies: the dispatcher's environment (OPENAI_BASE_URL) for a container run, the embedding product's gateway settings in-process.
API token	`token`	Secured	No		Bearer token for the endpoint. Blanked on every workspace-scoped read. When absent the executor's default applies: the dispatcher's environment (OPENAI_API_KEY) for a container run, the embedding product's gateway settings in-process.
Temperature	`temperature`	Slider	No		Sampling temperature. Lower is more deterministic. Blank sends none, so the provider's default applies; newer reasoning models reject any other value.
Max tokens	`maxTokens`	Number	No		Upper bound on the tokens the model may generate, sent as max_tokens. Blank sends none, so the provider's default applies; a max_completion_tokens key in Request parameters replaces it.
Seed	`seed`	Number	No		Optional sampling seed, for endpoints that honour one.
Request parameters	`parameters`	`json`	No		A JSON object merged into the request as sent: top_p, reasoning_effort, verbosity, max_completion_tokens, frequency_penalty, presence_penalty and so on. A key here wins over Temperature, Max tokens and Seed. Fails with INVALID_PARAM when it does not parse.
Response format	`responseFormat`	Select	No	`text`	Ask the model for free text or a JSON object.
JSON Schema	`jsonSchema`	Text Editor - Text	No		A JSON Schema object. With Response format json, the reply is held to it (response_format json_schema, strict) and validated before it is returned.
Files	`files`	Text	No		Comma-separated paths on the run workspace, read into the prompt context. Appended to the last user message's text, or to its last text part when it has content parts.
Max context bytes	`maxContextBytes`	Number	No	`65536`	Byte budget for the files read into context. Reading stops at the budget.
Images	`images`	Text	No		Images to send with the prompt, comma-separated: paths on the run workspace (PNG, JPEG, GIF or WEBP, read and sent inline) or https URLs (fetched by the provider). Attached to the last user message after its text. Needs a vision-capable model. This is a text param, so a presigned URL is stored and shown with the run; put private images on the workspace instead.
Image detail	`imageDetail`	Select	No		How closely the provider looks at each image. Blank sends nothing, so the provider's default applies. Applies to Images only, not to image parts inside Messages.
Max image bytes	`maxImageBytes`	Number	No	`5242880`	Largest workspace image to send, in bytes. A larger file fails with FILE_TOO_LARGE rather than being resized or skipped. Not sent to the provider, and URLs are not checked.
Output file	`outputFile`	Text	No		A path on the run workspace to write the full reply to, for a following uploadartifact node. The output result still carries the reply up to the results cap.

Results

Name	Description
`output`	The model's reply: the text, or the JSON string when Response format is json
`finishReason`	Why the model stopped, as the endpoint reported it
`model`	The model the endpoint actually served
`promptTokens`	Tokens consumed by the prompt
`completionTokens`	Tokens generated in the reply
`totalTokens`	Prompt plus completion tokens, the value a platform sums to meter usage
`reasoningTokens`	Reasoning tokens, when the endpoint reports them; empty otherwise
`cachedPromptTokens`	Prompt tokens served from the provider's cache, when reported; empty otherwise
`cost`	The call's cost as the endpoint reports it (OpenRouter usage.cost); empty otherwise

Example

Turn the list of changes in the workflow parameter changes into three release-note bullets. This is the summarise task in Use AI tasks.

Field	Value
Task name	`summarise`
Model	`openai/gpt-4o-mini`, or another model your endpoint serves
System prompt	`You write release notes for busy readers. Plain language, no marketing.`
Prompt	The text below
Max tokens	`300`
Endpoint	Blank, so the dispatcher's default applies
API token	Blank, so the dispatcher's default applies

Prompt

Summarise these changes as three short bullet points:
 
$(params.changes)

The task returns:

Result	Value
`output`	The three bullets
`model`	The model the endpoint served, which can be more specific than the one you asked for
`totalTokens`	The tokens the call used

A later task reads the reply as $(tasks.summarise.results.output), inserted as written. To use your own token, store it as a secured workspace parameter and enter its reference in API token, such as $(workspace.params.ai-token).

Common problems

Symptom	Cause	Fix
The task fails with `MISSING_PARAM`	There's no Prompt or messages, or no endpoint or token from the task or the dispatcher.	Give Prompt, or set Endpoint and API token, or ask your operator for defaults.
The task fails with the reason `ResultsTooLarge`	The reply took the task's results past 4096 bytes, the limit on Flow's Kubernetes dispatcher.	Lower Max tokens, or set Output file and pass the file on through the run workspace.
The task fails with `INVALID_RESPONSE`	With Response format `json`, the reply wasn't JSON, or didn't match JSON Schema.	Tighten the prompt or the schema.
A shell task that reads `output` fails on a quote in the reply	Flow inserts the reply as written, quotes and line breaks included.	Read it in a quoted heredoc, as in Use the reply in a later task.