Skip to main content
Version: v5.1

AI Converse

Overview#

The AI Converse task is a workflow task component that enables your workflow to interact with the AI service by programmatically creating a conversation.

AI Converse sends user prompts to the AI service, receives the AI-generated response, and makes it available as the result of the task. This task is designed for flexible integration with AI-powered conversational APIs, supporting dynamic configuration and secure access.

Typical use cases#

The AI Converse task is useful for:

  • Integrating AI-powered questions and answers sessions, or chat sessions into business workflows.
  • Automating compliance checks, document analysis, or conversational tasks.
  • Chaining AI responses with other Workflow tasks for advanced automation.

AI Converse features#

The AI Converse task offers the following features:

  • Token-based Authentication: Supports secure API calls using bearer tokens.
  • Flexible Prompting: Accepts both user and system prompts for advanced AI conversation control.
  • Synchronous Execution: Waits for the AI service response before completing the task.
  • Error Handling: Returns clear error messages for invalid input or failed service calls.

Input parameters#

ParameterTypeRequiredDescription
_teamIdStringYesThe AI Service team identifier.
_userPromptStringYesThe user's prompt or question for the AI Service.

Note: The authentication token and namespace filter are automatically taken from the workflow context (context.getToken(), context.getNamespace()).

How AI Converse works#

The AI Converse task operates using the following steps:

  1. Input extraction: The AI Converse task reads _teamId, _userPrompt, and _converse_id from the task’s input parameters.
  2. Payload Construction: Builds a JSON payload in the task. See example code below.
{  "_teamId": "<teamId>",  "_input": { "message": "<userPrompt>" }}

  1. Endpoint Resolution: Constructs the AI service endpoint URL using protocol, server, port, base URL, and conversation path from the workflow context. Appends ?sync=true and nsfilter as query parameters.

  2. Authentication: Adds an Authorization: Bearer <token> header if a token is present in the workflow context.

  3. Service Call: Sends a synchronous HTTP POST request to the AI Service with the constructed payload.

  4. Response Handling:

  • If the response is HTTP 2xx and valid JSON, it returns the parsed response as the task result.
  • If the response is not JSON or not HTTP 2xx, it returns a run-time exception with the error details.

Example Workflow definition#

{    "_name": "AI Conversation with Code Assistant",    "_description": "AI Conversation with Code Assistant",    "_namespaces": [        "{{nsfilter}}"    ],    "_userType": "ai_task",    "_taskDefs": [        {            "_name": "ai_conversation",            "_type": "AI_CONVERSE",            "_sequenceno": 1,            "_retryCount": 0,            "_inputParams": {                "_teamId": "f52e4d63-30e1-4507-af1a-881cb06a898f",                "_userPrompt": "Add a function that returns a list of NamedUserCollections from Item Service"            }        }    ]}

Output#

Output is based on either a successful outcome or an error:

  • On success: Returns a JSON representing the AI service’s JSON response with _output and _id properties.
  • On error: Throws a RuntimeException with details from the AI Service or HTTP error.