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.
|
Field |
Required |
Default Value |
Description |
|---|---|---|---|
|
|
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. |
|
|
Yes |
N/A |
Adds one Markdown request message sent to the model. Add additional user messages only when the conversation needs distinct request turns. |
|
|
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.
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.
|
Field |
Required |
Default Value |
Description |
|---|---|---|---|
|
|
Yes |
N/A |
Selects credentials for the model provider. The chosen credentials must support the selected provider and model. |
|
|
Yes |
N/A |
Selects the provider that serves the model. Changing it can change the available model and endpoint choices. |
|
|
When the selected provider requires it |
N/A |
Sets the provider-specific endpoint. It is shown only for providers that require an endpoint setting. |
|
|
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. |
|
|
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. |
|
|
No |
N/A |
Controls probability-based token selection where the provider supports it. Normally leave it blank unless you are deliberately tuning sampling. |
|
|
No |
N/A |
Limits candidate tokens where the provider supports it. Normally leave it blank unless you are deliberately tuning sampling. |
|
|
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.
|
Field |
Required |
Default Value |
Description |
|---|---|---|---|
|
|
No |
N/A |
Selects credentials used when the MCP server requires authentication. |
|
|
Yes |
N/A |
Enter the complete approved server address, including its path and any query values. |
|
|
No |
N/A |
Limits how long a tool request may wait for this MCP server. |
|
|
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.