AI Chat task

On this page

Use an AI Chat task when an AI model must classify, summarize or generate content, return structured data, or use approved tools. A model is the AI service that processes the messages you configure.

Messages

On Messages, add User messages for the request and System messages for behaviour, constraints, and policy.

ai-chat-messages.png

Field

Required

Default Value

Description

Memory window (messages)

No

Blank (no memory)

Enter 2 to 100 to share a window of conversation messages within the workflow run. A smaller window evicts older messages from the shared history.

User Message

Yes

N/A

Adds one Markdown request message sent to the model. Add additional user messages only when the conversation needs distinct request turns.

System Message

No

N/A

Adds one Markdown instruction defining behaviour, constraints, tone, or policy for the model. Use it for durable guidance rather than placing policy only in a user request.

Use the Messages tab's add control to add another User Message or System Message, and its remove control to remove a message that is no longer needed.

To use memory, enter a whole number from 2 to 100 in Memory window (messages). Leave it blank for no memory; no window size is filled in automatically. Tasks with a memory window share history within the run. A smaller window can remove messages that a later task would otherwise use. Clear the field to stop using memory for this task.

When chat memory is cleared

Chat history is scheduled for deletion when the workflow run completes, fails, is aborted, times out, or is terminated. This includes a failure caused by exceeding the workflow task quota.

Pausing retains history. Automatic task retries continue the same history. A failed request may already have saved its user message, so retries can leave repeated messages; memory is not an exact record of successful turns.

The message window can evict older messages while the run is active; it is a message count, not a time-based expiry. Clearing Memory window (messages) stops this task from using memory; it does not clear history shared by other enabled tasks in the run.

Test AI chat is always stateless, even when workflow-run memory is enabled. Templates copy the setting, not the history.

Model

On Model, select credentials, provider, and model. Adjust temperature, top-p, and top-k only when output style or repeatability requires it. Add a response JSON schema when the next task needs structured output.

ai-chat-model.png

Field

Required

Default Value

Description

Credentials

Yes

N/A

Selects credentials for the model provider. The chosen credentials must support the selected provider and model.

Provider

Yes

N/A

Selects the provider that serves the model. Changing it can change the available model and endpoint choices.

Endpoint

When the selected provider requires it

N/A

Sets the provider-specific endpoint. It is shown only for providers that require an endpoint setting.

Model

Yes

N/A

Selects or enters the model used to process the messages. Choose a model available to the selected credentials and suitable for the required response.

Temperature

No

N/A

Controls output variation where the provider supports it. Leave it blank to use the provider default; use a lower value when repeatability matters.

Top P

No

N/A

Controls probability-based token selection where the provider supports it. Normally leave it blank unless you are deliberately tuning sampling.

Top K

No

N/A

Limits candidate tokens where the provider supports it. Normally leave it blank unless you are deliberately tuning sampling.

Response JSON Schema

No

N/A

Supplies an object schema for structured AI output. Use it when the next task needs a predictable JSON shape; the schema itself must be valid JSON.

Successful AI responses retain usage and result and may additionally contain metadata.finishReason when the provider response supplies a finish reason. Missing metadata does not prove that a response was complete or accepted. No prompt, response text, or refusal text is included in this metadata.

An Azure provider endpoint must use HTTPS and an allowed public destination.

For structured output, use a schema whose root type is object. The model's support for native structured responses depends on the provider, but the final response must still match the configured schema. Invalid JSON or a schema mismatch fails the AI task instead of passing an unexpected value to the next task. A schema mismatch does not trigger a separate repair attempt. The task's configured Retry settings still apply. A workflow-task retry runs the AI operation again.

References to definitions within the same schema are supported. References that load a separate schema from a URL or file are not supported.

MCP servers

MCP is a way for an AI model to use external tools. Enter its complete Server URL, request timeout, and an optional tool filter. The filter applies separately to each configured server. A blank filter permits all tools advertised by that server; select specific tools when the task needs a narrower set.

When the task runs, the selected model processes the messages and may use those allowed tools. A tool can perform actions allowed by its remote credentials, so use only trusted servers and appropriate credentials.

Add an MCP server only when the AI task needs an approved external tool. Each configured server has the following fields.

ai-chat-mcp-servers.png

Field

Required

Default Value

Description

Credentials

No

N/A

Selects credentials used when the MCP server requires authentication.

Server URL

Yes

N/A

Enter the complete approved server address, including its path and any query values.

Request time out in seconds

No

N/A

Limits how long a tool request may wait for this MCP server.

Tool Filter

No

N/A

Lists the server tools available to this AI task. Select only tools the task needs so the model cannot use unnecessary tools.

Use Add MCP Server to configure another approved server and the remove control on a server to remove it.

SimWorkflow supports Streamable HTTP for MCP servers.

MCP Server URLs must use HTTP or HTTPS and an allowed public destination. Put authentication in the Credentials field; leave it unset only when the server supports anonymous access. Enter a fixed address; SimWorkflow expressions are not supported in Server URL.

Test AI chat

Click Test AI chat to run the currently configured AI Chat form with its current task input. Inspect the result to find credential, prompt, or configuration errors early. Testing does not save, publish, or start the workflow.

Troubleshoot AI failures

Check credentials, provider, model, messages, schema and MCP server settings when an AI Chat task fails. Check the category shown by Test AI chat or the failed workflow task.

For a configuration or credential error, confirm the provider, model, endpoint and selected credentials.

For an MCP connection or tool-list error, check the server address, Streamable HTTP endpoint, authentication and availability.

For a tool-execution error, check the tool configuration, credentials and availability before retrying. Review any remote side effects before retrying a tool that changes data.

For a schema mismatch, check the schema and prompt together and use a model suited to structured output. Recognized remote failures can include the service's diagnostic message, code and status, such as an unavailable model or invalid configuration.

AI Chat Test, model and tool discovery, and HTTP Test show a service failure's status, error code and message separately when available.

For HTTP tasks, inspect the failed task's output statusCode and body; larger, binary or malformed responses can be retained as task attachments under the existing limits. The remote response is separate from the short failure reason. Treat its contents as potentially sensitive. Configured workflow retries retain failed-attempt history and may repeat remote side effects.

Output

Required usage has nullable promptTokens/completionTokens and totalTokens (0 if unavailable); result is text, or JSON matching the configured response schema. Optional metadata.finishReason is included when supplied; known native reason spelling is retained, unfamiliar reasons become unknown. No reason is a universal refusal flag.

Example task output:

{
  "usage": {
    "promptTokens": 18,
    "completionTokens": 4,
    "totalTokens": 22
  },
  "result": "Account support",
  "metadata": {
    "finishReason": "stop"
  }
}

When something goes wrong: Correct credentials/model/provider options and structured schema when rejected. File input does not bypass model context limits; Chat output must fit task data limits and has no automatic file fallback. Search context must be explicitly mapped into a message; it is not injected automatically.