Basic Agent
Overview
The Basic Agent defines an AI-powered agent that can interact with users, use tools, and maintain conversation memory. This agent leverages large language models to provide intelligent responses and can be configured with custom prompts, tools, and behaviors for various conversational and automation scenarios.
Configuration Details
name
The unique name of the AI agent within the workflow.
String
Yes
-
start
Indicates if this is the starting agent of the workflow.
Boolean
No
false
transition
Defines the transition to the next flow node after this agent completes. See TransitionDef
Object
No
-
answerAfterFinish
Whether the agent should provide an answer message after finishing execution.
Boolean
No
false
answerMessage
Custom message to display when the agent finishes (if answerAfterFinish is true).
String
No
-
aiModel
The AI model to use for this agent. Supports various models like GPT-4, Claude, etc.
String
No
"gpt-4o"
llmConfig
Advanced configuration for the LLM including temperature, max tokens, etc. See LLMConfigDef
Object
No
-
systemMessage
System message that defines the agent's role and behavior context.
String
No
"You are a helpful AI Assistant."
userMessage
User message template that defines how user input is presented to the AI. Can include expressions.
String
Yes
-
userIdentityExpression
Expression to identify the user context for personalized responses.
String
No
-
maxToolExecutions
Maximum number of tool executions allowed in a single agent run to prevent infinite loops.
Integer
No
10
memory
Memory configuration for maintaining conversation context across interactions. See ChatMemoryDef
Object
No
-
output
Output schema definition that specifies the structure of the agent's response. See DataSchemaDef
Object
Yes
-
tools
List of tools/functions that the AI agent can use to perform actions or retrieve information. See ToolForAIDef
List
No
[]
askUserForToolsInput
Whether the agent should ask the user for additional input when using tools.
Boolean
No
false
agentOutcomes
List of outcome handlers that define actions to take based on agent execution results. See OnAgentOutcomeDef
List
No
[]
loginRequired
Whether user authentication is required to interact with this agent.
Boolean
No
-
groupConfig
Group configuration for multi-user or team-based agent interactions. See GroupConfigDef
Object
No
-
multiAgentCollaboration
Multi-agent collaboration enables AI agent to delegate tasks to other collaborator agents. When enabled, the agent acts as a supervisor, coordinating responses from its collaborator agents.
Object
No
groupConfig
Configuration for the AI Agent in a group context. This configuration only applies when the agent is part of a group. See GroupConfigDef
Object
No
Common Configuration Objects
LLMConfigDef
LLM Configuration Definition. Defines the configuration for AI Language Models used by AI agents. Includes provider settings, authentication, and parameter overrides for fine-tuning model behavior.
provider
The name of the LLM provider
String
No
apiKey
The API key to access the AI Language Model provider
String
No
overrideParams
Parameters to override for the provider. These settings will take precedence over default model parameters. See LLMParamsDef
Object
No
LLMParamsDef
LLM Parameters Definition. Defines configuration parameters for Language Model behavior including sampling settings, token limits, penalties, and other model-specific options that control AI response generation.
model
The specific model to use for generating responses
String
No
-
temperature
The sampling temperature (0.0 to 2.0). Higher values make output more random, lower values more focused
Double
No
-
topP
The top-p sampling parameter (0.0 to 1.0). Controls nucleus sampling for token selection
Double
No
-
n
The number of completions to generate for each prompt
Integer
No
-
logprobs
The number of log probabilities to return for each token
Integer
No
-
echo
Whether to echo back the prompt in the response
Boolean
No
-
stop
Sequences where the model should stop generating further tokens
List
No
[]
maxTokens
The maximum number of tokens to generate in the response
Integer
No
-
presencePenalty
Presence penalty parameter (-2.0 to 2.0). Positive values penalize new tokens based on whether they appear in the text so far
Double
No
-
frequencyPenalty
Frequency penalty parameter (-2.0 to 2.0). Positive values penalize new tokens based on their existing frequency in the text
Double
No
-
logitBias
Logit bias configuration. Maps token IDs to bias values (-100 to 100) to increase or decrease likelihood of specific tokens
Map<String, Integer>
No
-
required
Additional required parameters specific to the model or provider
Object
No
-
ChatMemoryDef
Configures how AI agents manage conversation memory including short-term message windows, memory optimization through summarization, and long-term memory for persistent context across sessions.
memoryId
Unique identifier for the memory session
String
No
-
memoryType
Type of memory management strategy
String
No
"message_window"
maxMessages
Maximum number of messages to retain in memory
Integer
No
10
maxTokens
Maximum number of tokens to retain in memory (alternative to maxMessages)
Integer
No
-
memoryOptimizer
Configuration for memory optimization strategies like summarization
Object
No
-
longTermMemory
Configuration for long-term memory that persists across sessions
Object
No
-
MemoryOptimizerDef
Memory Optimizer Definition. Configures strategies for optimizing memory usage through summarization and other compression techniques to maintain relevant context while reducing memory footprint.
summarization
Configuration for conversation summarization to compress older messages
Object
No
ConversationSummarizationDef
Conversation Summarization Definition. Configures how older conversation messages are summarized to compress memory while retaining important context and recent interactions.
retainedMessages
Number of recent messages to retain without summarization
Integer
No
2
promptMessage
Custom prompt for guiding the summarization process
String
No
-
LongTermMemoryDef
Long Term Memory Definition. Configures persistent memory that survives across conversation sessions. Supports different memory types (semantic, episodic, procedural) and scopes (global, local) for various use cases.
memoryId
Unique identifier for the long-term memory instance
String
No
-
scope
Scope of the long-term memory: 'global' (shared across agents) or 'local' (agent-specific)
String
No
-
memoryType
Type of long-term memory: semantic (facts/knowledge), episodic (events/experiences), or procedural (skills/processes)
String
No
"episodic"
DataSchemaDef
Data Schema Definition. Defines the structure and validation rules for data used in AI workflows. Contains JSON Schema specifications that ensure data integrity and provide type safety for agent interactions and data transformations.
schema
JSON Schema definition that describes the structure, types, and validation rules for data objects
JsonNode
Yes
ToolForAIDef
Tool Definition for AI Agents. Defines a tool or function that can be used by AI agents to perform specific tasks or access external services. Supports both standard tool execution and Model Context Protocol (MCP) integration for enhanced capabilities.
name
Unique name of the tool that will be used by AI agents to invoke it
String
Yes
type
Type of tool execution. 'standard' for direct execution, 'mcp' for Model Context Protocol integration
String
No
description
Description of what the tool does and how to use it
String
No
parameters
Input parameters schema definition for the tool
Object
No
output
Output schema definition for the tool response
Object
No
execution
Tool execution configuration including endpoint and method
Object
No
mcpClient
MCP client configuration for Model Context Protocol tools. See McpClientDef
Object
No
McpClientDef
MCP Client Definition. Configuration for connecting to a Model Context Protocol (MCP) server. Defines the server URL, authentication details, and tool filtering options for MCP integration.
url
The URL of the MCP server endpoint
String
Yes
auth
Authentication details for the MCP client. If not specified, no authentication is used. See McpAuthDef
Object
No
toolFilter
Filter for MCP tools that can be used to select specific tools based on their properties. If not specified, all tools are included. See McpToolFilterDef
Object
No
McpAuthDef
MCP Authentication Definition. Specifies authentication details for connecting to Model Context Protocol (MCP) servers. Supports both bearer token and custom header-based authentication methods for secure MCP communication.
type
The type of authentication to use for the MCP client. Allowed values: "bearer", "header"
String
Yes
bearerToken
The bearer token to use for authentication. Required when type is 'bearer'
String
No
headers
Key-value pairs of headers to include in the request for authentication. Required when type is 'header'
Map<String, String>
No
McpToolFilterDef
MCP Tool Filter Definition. Filters MCP tools that can be used to select specific tools based on their properties. Supports various filtering strategies: include all tools, include specific tools, exclude specific tools, or use custom expressions for advanced filtering logic.
type
The type of filter to apply to the MCP tools. Allowed values: "all", "include", "exclude", "expression"
String
Yes
includedTools
List of MCP tool names to include when the filter type is 'include'
List
No
excludedTools
List of MCP tool names to exclude when the filter type is 'exclude'
List
No
expression
A custom jq expression to filter MCP tools when the filter type is 'expression'. The expression should evaluate to true for tools that should be included. The input is a list of tool objects with properties: name, description
String
No
OnAgentOutcomeDef
Agent Outcome Definition. Defines conditional actions to be performed based on the outcome of an AI agent's execution. Allows for branching logic, workflow control, and custom responses based on agent results or specific conditions.
condition
Expression that must evaluate to true for this outcome to be matched
String
Yes
-
finish
Whether the agent should finish execution after this outcome action is performed
Boolean
No
true
transition
The transition definition specifying the next step in the workflow when this outcome is matched
Object
No
-
answerAfterFinish
Whether to provide an answer message after finishing this outcome action
Boolean
No
false
GroupConfigDef
Group Configuration Definition. Defines the behavior of AI agents when operating in group or multi-agent contexts. Controls how agents interact with other agents and respond to messages in collaborative environments such as group chats, team channels, or multi-agent workflows.
directMessageOnly
Whether the agent should only respond to messages that are directly addressed to it
Boolean
No
false
TransitionDef
Defines the flow control mechanism for moving between different states or agents in a workflow. Specifies either a target destination or workflow termination, enabling complex branching and routing logic in AI agent conversations.
end
Whether this transition marks the end of the workflow execution. When true, the workflow terminates. When false, execution continues to the target agent
Boolean
No
false
targetId
The unique identifier of the target agent or node to transition to. Must correspond to a valid agent name defined in the workflow. Ignored if 'end' is true
String
No
-
Example Configuration
{
"name": "customerSupportAgent",
"type": "aiagent",
"start": false,
"aiModel": "gpt-4o",
"systemMessage": "You are a helpful customer support agent for an e-commerce company. Be professional, empathetic, and provide accurate information.",
"userMessage": "Please help the customer with their inquiry: {{userInput}}",
"userIdentityExpression": "{{user.name}} (ID: {{user.id}})",
"maxToolExecutions": 5,
"llmConfig": {
"provider": "openai",
"apiKey": "sk-1234567890abcdef",
"overrideParams": {
"model": "gpt-4o",
"temperature": 0.7,
"maxTokens": 1000,
"presencePenalty": 0.1,
"frequencyPenalty": 0.1,
"stop": ["END_CONVERSATION"]
}
},
"memory": {
"memoryId": "customer-session-{{user.id}}",
"memoryType": "message_window",
"maxMessages": 20,
"maxTokens": 4000,
"memoryOptimizer": {
"summarization": {
"retainedMessages": 5,
"promptMessage": "Summarize the key points and customer issues from this support conversation"
}
}
},
"output": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "string",
"description": "The agent's response to the customer"
},
"resolved": {
"type": "boolean",
"description": "Whether the customer's issue has been resolved"
},
"category": {
"type": "string",
"enum": ["order", "product", "shipping", "refund", "other"],
"description": "Category of the customer inquiry"
},
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "urgent"],
"description": "Priority level of the issue"
}
},
"required": ["response", "resolved", "category"]
}
},
"tools": [
{
"name": "orderLookup",
"type": "standard",
"description": "Look up order details by order ID",
"parameters": {
"schema": {
"type": "object",
"properties": {
"orderId": {"type": "string"}
},
"required": ["orderId"]
}
},
"execution": {
"endpoint": "https://api.ecommerce.com/orders/{orderId}",
"method": "GET"
}
},
{
"name": "createRefund",
"type": "standard",
"description": "Create a refund for an order",
"parameters": {
"schema": {
"type": "object",
"properties": {
"orderId": {"type": "string"},
"amount": {"type": "number"},
"reason": {"type": "string"}
},
"required": ["orderId", "amount", "reason"]
}
},
"execution": {
"endpoint": "https://api.ecommerce.com/refunds",
"method": "POST"
}
},
{
"name": "weatherTools",
"type": "mcp",
"description": "Access weather information and forecasts via MCP server",
"mcpClient": {
"url": "https://mcp-weather.example.com/v1",
"auth": {
"type": "bearer",
"bearerToken": "sk-weather-api-key-1234567890"
},
"toolFilter": {
"type": "include",
"includedTools": ["get-current-weather", "get-forecast", "get-weather-alerts"]
}
}
},
{
"name": "fileOperations",
"type": "mcp",
"description": "File system operations via MCP server with custom header authentication",
"mcpClient": {
"url": "https://mcp-files.internal.com/api",
"auth": {
"type": "header",
"headers": {
"Authorization": "ApiKey your-api-key-here",
"X-App-ID": "customer-support-agent"
}
},
"toolFilter": {
"type": "exclude",
"excludedTools": ["delete-file", "modify-permissions"]
}
}
}
],
"askUserForToolsInput": false,
"agentOutcomes": [
{
"condition": "{{output.resolved}} == true",
"finish": true,
"answerAfterFinish": true,
"transition": {
"targetId": "satisfactionSurveyAgent"
}
},
{
"condition": "{{output.priority}} == 'urgent'",
"finish": false,
"transition": {
"targetId": "escalationAgent"
}
}
],
"groupConfig": {
"directMessageOnly": true
},
"loginRequired": true,
"transition": {
"targetId": "followupAgent"
},
"answerAfterFinish": true,
"answerMessage": "Thank you for contacting customer support. Is there anything else I can help you with today?"
}Last updated