Trigger Agent

Trigger an AI agent chat with templated user queries. This function allows you to programmatically interact with AI agents using template strings with variable substitution. The function processes template variables, triggers the agent conversation, and returns the agent's response.

Technical Name: TriggerAgentFunc

Properties

• Execution Mode: SYNC
• Type: NATIVE
• Category: System Functions
• Function ID: 8a2e4c9f-1b3d-4f5a-8e9c-2d6f8a1b4e7c

Input Schema

Required Parameters

Optional Parameters

[Image placeholder: TriggerAgent function configuration panel]

Input Example

Basic Query Without Variables

{
  "agentUUID": "a7b9c4d2-3e5f-4a1b-9c8d-7e6f5a4b3c2d",
  "userQuery": "Analyze the sales data for Q1 2024"
}

Query With Template Variables

{
  "agentUUID": "a7b9c4d2-3e5f-4a1b-9c8d-7e6f5a4b3c2d",
  "userQuery": "Create order for {userId} with status {status} and amount {amount}",
  "variableMappings": {
    "userId": "user-123",
    "status": "pending",
    "amount": "99.99"
  }
}

Query With File Attachment

{
  "agentUUID": "a7b9c4d2-3e5f-4a1b-9c8d-7e6f5a4b3c2d",
  "userQuery": "Analyze this document: {documentType}",
  "fileUUID": "file-uuid-here",
  "variableMappings": {
    "documentType": "invoice"
  }
}

Output Schema

Output Example

Success Response

{
  "success": true,
  "conversationId": "c9d1e6f4-5g7b-6c3d-0e1f-9g8c7d6e5f4g",
  "runId": "b8c0d5e3-4f6a-5b2c-9d0e-8f7b6c5d4e3f",
  "agentId": "a7b9c4d2-3e5f-4a1b-9c8d-7e6f5a4b3c2d",
  "agentName": "Sales Analysis Agent",
  "processedQuery": "Create order for user-123 with status pending and amount 99.99",
  "agentResponse": "Order created successfully. Order ID: ORD-12345"
}

Error Response

{
  "success": false,
  "errorMessage": "Agent not found with ID: invalid-uuid"
}

[Image placeholder: TriggerAgent output visualization]

How It Works

The function performs the following steps:

1. Parse Input: Validates and parses input parameters
2. Process Template: Uses Spring AI PromptTemplate to replace {variable} placeholders with values from variableMappings
3. Load Agent: Retrieves the AI agent by UUID from the repository
4. Generate IDs: Creates a unique run ID for this execution
5. Create Chat Request: Builds an AI chat request with the processed query
6. Execute Agent: Triggers the agent chat in a separate thread to preserve execution context
7. Extract Response: Extracts string content from the agent's response (only supports StringAgentOutput)
8. Return Result: Returns success status, agent information, processed query, and response

Template Variable Processing

The function uses Spring AI PromptTemplate for variable substitution:

• Format: Variables are enclosed in curly braces: {variableName}
• Substitution: Values from variableMappings replace the variables
• Missing Variables: If a variable in the template has no mapping, it remains as-is
• No Mappings: If variableMappings is null or empty, the query is returned as-is

Template Examples

{
  "userQuery": "Hello {name}, your order {orderId} is {status}",
  "variableMappings": {
    "name": "John",
    "orderId": "ORD-123",
    "status": "shipped"
  }
}

Result: "Hello John, your order ORD-123 is shipped"

Use Cases

Dynamic Agent Queries

Trigger agents with dynamic data from workflows:

{
  "agentUUID": "{{workflow.agentId}}",
  "userQuery": "Analyze customer {customerId} transaction history",
  "variableMappings": {
    "customerId": "{{workflow.customerId}}"
  }
}

Workflow Automation

Use AI agents in automated workflows:

Start → FetchMData → TriggerAgent → ProcessResponse → End

[Image placeholder: Workflow example]

Document Analysis

Send documents to agents for analysis:

{
  "agentUUID": "document-analysis-agent-uuid",
  "userQuery": "Analyze this {documentType} and extract key information",
  "fileUUID": "{{uploadedFileId}}",
  "variableMappings": {
    "documentType": "invoice"
  }
}

Notes

• Agent Type: Only supports agents with StringAgentOutput response type
• Template Processing: Uses Spring AI PromptTemplate for variable substitution
• Thread Isolation: Executes agent chat in a separate thread to preserve workflow execution context
• File Attachments: Optional file can be attached to the chat request
• Error Handling: Returns error message in errorMessage field if operation fails
• Agent Validation: Validates that the agent exists before processing
• Variable Mappings: All values in variableMappings are treated as strings

Limitations

• Output Type: Only supports StringAgentOutput agents. Other output types will throw an exception
• Synchronous Execution: The function waits for the agent response before returning
• Template Variables: Variables must match exactly (case-sensitive) between template and mappings

Related Functions

• Call External API - Call external APIs and services
• Run JavaScript Code - Execute custom JavaScript logic
• Calculate Expression - Perform calculations and formulas