AI Agent

Core LLM-powered agent node for building sophisticated conversational workflows with autonomous reasoning capabilities, extensive tool integration, and RAG-powered knowledge retrieval.

Configuration

Connections

Agentic Loop Configuration

AI Agents operate through an autonomous reasoning cycle. For a detailed explanation of how this works, see Agentic Loop Concepts.

Loop Control Parameters

The agent's reasoning behavior is controlled through these configuration parameters:

Input Parameters

Template Variables

AI Agents have access to both agent-specific context and the full workflow context object. Use these variables in your system message and prompts:

Agent-Specific Context

These variables are unique to AI agent nodes:

Universal Workflow Context

AI Agents also have access to the complete workflow context. For detailed documentation, see Workflow Context.

Key Context Categories:

Common Agent Patterns

Personalized Responses:

Hello {{ctx.user.login}}! I'm {{ctx.agent_name}}, your assistant for {{ctx.app_slug}}.

Using knowledge: {{ctx.knowledge_base}}
Previous context: {{ctx.conversation_history}}

Multi-Node Integration:

Based on the data from {{ctx.nodes.dataProcessor.outputs.summary}} and 
user preference {{ctx.vars.displayMode}}, I'll provide a {{ctx.user.roles[0] === "admin" ? "detailed" : "standard"}} response.

Conditional Logic with Memory:

{{ctx.memory.tool_calls ? "I remember using these tools: " + ctx.memory.tool_calls : "This is our first interaction."}}

Knowledge context: {{ctx.knowledge_base}}

Default System Message

You are {{ctx.agent_name}}, a helpful assistant. Use this context: {{ctx.knowledge_base}}

Configuration Examples

Tool Selection Strategies

AI Agents can use any node type as tools, providing unlimited extensibility for agentic workflows. The agent's reasoning process includes intelligent tool selection based on task requirements and available capabilities.

Tool Selection Decision Flow

Tool Selection Criteria

The agent's reasoning process considers these factors when selecting tools:

1. Task Complexity - Simple responses vs. multi-step operations
2. Data Requirements - Input/output formats, storage needs, transformations
3. External Dependencies - API calls, third-party services, real-time data
4. Performance Considerations - Response time, resource usage, concurrency
5. Error Handling - Fallback options, retry mechanisms, validation needs

Universal Tool Integration

AI Agents can use any node type as a tool, providing unlimited extensibility. Each connected node becomes a capability the agent can autonomously invoke during its reasoning process.

Tool Configuration Options

When any node is connected as a tool, additional configuration options become available to control tool behavior:

Tool Call Events for Chat Clients

Configure real-time event streaming to Chat clients during tool execution:

Start Event Payload - Sent to Chat clients before tool execution begins:

{
  "toolName": "{{ctx.node_name}}",
  "operation": "{{ctx.inputs.operation_type}}",
  "status": "starting"
}

End Event Payload - Sent to Chat clients after tool execution completes:

{
  "toolName": "{{ctx.node_name}}",
  "success": {{ctx.outputs.success}},
  "resultCount": {{ctx.outputs.count}},
  "status": "completed"
}

Available Context Variables:

• ctx.inputs.* - All tool input parameters (available in start and end events)
• ctx.outputs.* - Tool execution results (available in end events only)
• ctx.node_name - Name of the connected node

Chat Client Use Cases:

• Loading Indicators: Show "Searching..." when search tool starts
• Progress Updates: Display intermediate status during long-running operations
• Real-time Feedback: Update chat interface based on tool activity
• User Experience: Keep users informed during tool execution

Intelligent Tool Composition

Agents autonomously combine tools to solve complex tasks:

Best Practices

Tool Integration Guidelines

Tool Selection and Organization

Tool Quantity Management:

• Optimal Range: 5-15 tools for most use cases
• Maximum Limit: 20 tools (performance degrades beyond this)
• Minimum Viable: Start with 3-5 essential tools, expand based on actual needs

Tool Description Quality:

• Be Specific: Describe exactly what the tool does and when to use it
• Include Examples: Provide sample inputs and expected outputs
• Clear Boundaries: Specify what the tool does NOT do to avoid confusion
• Parameter Guidance: Explain each parameter's purpose and format

// Good Tool Description
"Search the customer database by email, phone, or customer ID. 
Returns customer profile including order history and preferences. 
Use when user asks about account details or order status."

// Poor Tool Description  
"Search customers"

Tool Naming Conventions

Descriptive Names:

• ✅ SearchCustomerDatabase, CalculateShippingCost, SendWelcomeEmail
• ❌ Tool1, Query, Process, Handler

Consistent Patterns:

• Action + Object: CreateTicket, UpdateInventory, DeleteUser
• Domain + Action: CustomerLookup, PaymentProcess, InventoryCheck

System Prompt Design

Tool Usage Guidance in Prompts:

You are a customer service agent with access to these tools:

PRIORITY TOOLS (use first):
- SearchCustomerDatabase: For account lookups and order history
- CreateSupportTicket: For issues requiring escalation

SECONDARY TOOLS (use as needed):
- SendEmail: For follow-up communications
- UpdateCustomerNotes: For documenting interactions

Always search the customer database before creating tickets.

Performance Optimization

Conversation Management

Memory Configuration:

• Short Conversations: lastMessagesCount: 3-5
• Complex Tasks: lastMessagesCount: 8-12
• Long-term Sessions: Enable enableLongTermMemory sparingly

Token Management:

• Monitor total context size (system prompt + conversation + tool descriptions)
• Use concise but descriptive tool documentation
• Consider tool result caching for expensive operations

Tool Architecture Patterns

Layered Tool Strategy

Core Tools (Always Available):

• Essential business functions (search, create, update)
• Error handling and validation tools
• Basic communication tools

Conditional Tools (Context-Dependent):

• Specialized domain tools
• Integration-specific tools
• Advanced processing tools

Tool Dependency Management

Independent Tools:

✅ Each tool works standalone
✅ No hidden dependencies between tools
✅ Clear input/output contracts

Coordinated Tools:

⚠️ Document tool execution order in system prompt
⚠️ Handle partial failures gracefully
⚠️ Provide fallback options when tool chains fail

Quality Assurance

Testing Strategy

Individual Tool Testing:

1. Test each tool independently with various inputs
2. Verify error handling and edge cases
3. Confirm output format consistency
4. Validate parameter validation

Agent Integration Testing:

1. Test tool selection accuracy with realistic scenarios
2. Verify agent chooses appropriate tools for different queries
3. Test tool combination workflows
4. Validate error recovery and fallback behavior

Monitoring and Optimization

Key Metrics to Track:

• Tool usage frequency and success rates
• Average turns per conversation
• Tool selection accuracy
• User satisfaction scores
• Response time and token usage

Optimization Signals:

• Too Many Unused Tools: Remove or consolidate rarely used tools
• Poor Tool Selection: Improve tool descriptions and system prompt guidance
• High Turn Count: Review tool efficiency and agent logic
• Slow Responses: Reduce tool count or optimize tool performance

Troubleshooting

Common Issues

Infinite Loops

• Increase maxTurns if tasks legitimately require more iterations
• Review system prompt for circular reasoning patterns
• Ensure tools return clear success/failure indicators

Poor Tool Usage

• Verify tool descriptions are clear and specific
• Check that tool parameters match agent expectations
• Test tools independently before connecting to agent

Context Overflow

• Reduce lastMessagesCount if hitting token limits
• Optimize knowledge base chunk sizes
• Use more efficient prompt templates

Performance Monitoring

Monitor these metrics for optimal agent performance:

• Average turns per conversation
• Tool usage frequency and success rates
• Response time and token usage
• User satisfaction and task completion rates

Related Concepts

Within AI & Knowledge Ecosystem

• AI Sub-Agent - Multi-agent orchestration patterns and delegation strategies
• Knowledge Base - Advanced RAG implementation and semantic search optimization
• AI & Knowledge Overview - Ecosystem architecture and workflow composition patterns

Tool Integration Nodes

• Data & Storage Nodes - File operations, databases, and data management tools
• Code Execution Nodes - JavaScript, Python, and custom logic execution
• Integration Nodes - HTTP, webhooks, and third-party service connectivity
• Flow Control - Conditional logic, loops, and orchestration patterns

Next Steps:

• Multi-Agent Systems: AI Sub-Agent for delegation and orchestration
• Enhanced Context: Knowledge Base for RAG integration
• Tool Selection: Review individual node categories for specific tool capabilities