AI Agent

An intelligent orchestrator node that processes messages using AI and can autonomously call tools to fulfill requests.

Inputs

payload string | object

The user's message or query to send to the AI. Can be a string (simple message) or an object with structured input.

aiagent object

Optional configuration provided by the AI Model node. If not present, the node will use its default configuration.

aiagent.model string

The AI model to use (e.g., "anthropic/claude-3-sonnet"). Provided by AI Model node

aiagent.credentialRef string

Id of the AI Model node whose credentials the agent uses. Provided by AI Model node, which never puts the key itself on the message. A reference written or changed by another node is refused, and the provider and region always come from the AI Model node.

aiagent.apiKey string

Optional per-message key. Overrides the AI Model node's key, or supplies one in a flow with no AI Model node. It is hidden from the Debug panel and from what the agent sends on. For Bedrock, also set aiagent.authMethod to "apiKey"; without it a hand-set key is ignored and the agent uses the server's AWS credentials. Reading this field to get the AI Model node's key is deprecated.

aiagent.tools array

Array of tool definitions that the AI can call. Provided by Tool nodes.

Outputs

payload string | object

The AI's response. Format depends on Response Format setting:

• Text Only: Simple string response
• Structured Object: Object with response, metadata, and context

aiagent object

AI configuration and state information, passed downstream for use by other nodes (e.g., Guardrails)

agent_error object

If an error occurs during AI processing, contains {occurred: true, statusCode: 500, message, provider}, plus providerStatus and code when the provider supplied them — code: 'AUTH_ERROR' means the credentials configured in the AI Model node were rejected. Downstream nodes like Guardrails can detect and handle this.

Details

The AI Agent node is the core of the agentic system. It processes user messages, maintains conversation context, and can autonomously call tools to fulfill complex requests.

Configuration

System Prompt

Defines the AI's behavior and personality. This prompt sets the context for all interactions.

Response Format

• Text Only: Returns just the AI's text response in msg.payload. Best for simple use cases.
• Structured Object: Returns detailed object with response, metadata, tool calls, and conversation context. Best when you need debugging information or advanced features.

Max Tool Loop

Safety limit on sequential tool executions. Prevents infinite loops if a tool repeatedly fails or the AI gets stuck in a retry loop. Default: 10. Tracked per request in memory only.

Tool Execution Flow

When the AI decides to call a tool:

1. AI Agent sends a message to Tool Adapter (via AI Model node)
2. Tool Adapter executes the tool flow (output 2)
3. Tool flow ends with Tool Terminate
4. Result returns to AI Agent
5. AI processes the result and may call more tools or provide final answer

Connection Requirements

Required: Must be connected to an AI Model node which provides the model configuration and API credentials.

Optional: Connect Tool Adapter nodes before AI Agent to enable tool usage. Connect Guardrails node after AI Agent to apply safety filters.

Typical Usage

Simple Flow (with function tool)

┌────────┐   ┌──────────┐   ┌─────────────────┐   ┌──────────┐
│ inject │──▶│ AI Model │──▶│ Tool: Get Date  │──▶│ AI Agent │──▶ debug
└────────┘   └──────────┘   └─────────────────┘   └──────────┘

Healthcare Agent Flow (with FHIR tools)

┌────────────┐   ┌──────────┐   ┌───────────┐   ┌────────────────┐
│ User Query │──▶│ AI Model │──▶│ FHIR Tool │──▶│    AI Agent    │
└────────────┘   └──────────┘   └───────────┘   └───────┬────────┘
                                                        │
           ┌────────────────────────────────────────────┘
           ▼
┌──────────────┐   ┌─────────────────┐   ┌────────────┐
│  Guardrails  │──▶│ Update History  │──▶│  Response  │
└──────┬───────┘   └─────────────────┘   └────────────┘
       │
       ▼ (if PHI detected)
  ┌──────────┐
  │  BLOCKED │
  └──────────┘

Tool Adapter with Subflow

Tool Adapter has 2 outputs: (1) passes to next node, (2) executes tool flow

                               output 1 (passes config)
                         ┌─────────────────────────────▶ [AI Agent]
┌──────────┐   ┌─────────┴──────┐
│ AI Model │──▶│  Tool Adapter  │
└──────────┘   └─────────┬──────┘
                         │ output 2 (when AI calls tool)
    ┌────────────────────▼────────────────────────────────────┐
    │ Tool Subflow (green group)                              │
    │  ┌───────────────┐   ┌────────┐   ┌────────────────┐    │
    │  │ Prepare Input │──▶│  Auth  │──▶│ Tool Terminate │    │
    │  └───────────────┘   └────────┘   └────────────────┘    │
    └─────────────────────────────────────────────────────────┘

Examples

Simple Question:

msg.payload = "What is the weather like?";
return msg;

Output (Text Only): "I don't have access to real-time weather data..."

With Tool Usage:

// Input with tool available
msg.payload = "Search for patient John Smith";
// AI will call the search tool automatically
// Output: "I found 3 patients matching 'John Smith'..."

Structured Output:

{
  "response": "Hello! How can I assist you today?",
  "metadata": {
    "model": "anthropic/claude-3-sonnet",
    "toolsCalled": 0,
    "tokensUsed": 125
  },
  "context": {
    "conversationId": "abc123"
  }
}

Best Practices

• Set a clear system prompt that defines the AI's role and capabilities
• Use Text Only format for production, Structured Object for development/debugging
• Always connect to an AI Model node for reliability
• Add Guardrails node after AI Agent for PHI redaction in healthcare apps
• Monitor the agent_error flag for error handling