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.