AI Agent

Node catalog Artificial intelligence

On this page

Generates a plan and executes tools

Usage and specifics

Connect model, memory and tool components, or supply explicit configuration. maxIterations bounds tool calls. Tools with external effects must retain their approval rules.

Technical type : ai_agent. Runtime : nodulz.

Guided example

To check a first agent without an external write action:

Prepare an accessible model credential and choose a model available to that account.
Connect the manual trigger to the agent through execution connections. Connect the model component to the agent’s model port, or complete its explicit configuration.
Use the manual payload { "question": "Rephrase in one sentence: our meeting has been moved to tomorrow." }.
Set userPrompt to {{ input.question }} and systemPrompt to Reply in English, in one sentence, without adding facts..
Run and check the text in the output’s text property.

Then add one read tool with a destination you control. Connect it to the tools port, give it a unique name and describe when to use it. Ask for a task that requires this read and inspect the trace to verify the actual call. Mentioning a tool in the prompt or toolsJson does not replace its connection.

Output contains text, steps, iterations, usage, durationMs and trace. In a later step, read {{ nodes.agent1.text }}, adapting agent1 to the actual technical name. Answers may vary between calls: focus on facts, format and tools used.

maxIterations bounds agent turns, maxTokens bounds one call’s output and maxTotalTokens bounds this agent’s cumulative usage. Tools calling other models have their own usage. Start with a short task; increase a limit after identifying which one blocks progress.

For a tool that writes to a service, configure approval as needed and check resuming from history. Memory is optional: add it only if several exchanges need to share context.

Credentials and prerequisites

Create and configure the credential : ai-model

Create credentials in your nodulz instance’s Credentials area, then select them on the node. Availability depends on ownership and sharing. See the credentials guide for access and rotation.

Parameters

Names below are technical keys. Defaults are not a ready-to-run configuration: complete fields required by your operation. Paths containing [] describe list items; some fields depend on the selected mode.

Parameter	Type	Default	Values / limits
`credentialId`	`string`	-	-
`model`	`string`	`""`	-
`modelNodeId`	`string`	-	-
`fallbackModelNodeIds`	`array`	`[]`	-
`modelRoutes`	`array`	`[]`	-
`modelRoutes[].modelNodeId`	`string`	-	-; min 1
`modelRoutes[].combinator`	`enum`	`"and"`	`and`, `or`
`modelRoutes[].conditions`	`array`	-	-; min 1
`modelRoutes[].conditions[].field`	`string`	`""`	-
`modelRoutes[].conditions[].operator`	`enum`	`"equals"`	`equals`, `not_equals`, `contains`, `not_contains`, `gt`, `gte`, `lt`, `lte`, `empty`, `not_empty`
`modelRoutes[].conditions[].value`	`string`	`""`	-
`memoryNodeId`	`string`	-	-
`systemPrompt`	`string`	`"You are a helpful AI agent with access to tools."`	-
`userPrompt`	`string`	`""`	-
`agentMode`	`enum`	`"tools_agent"`	`tools_agent`, `react`
`maxIterations`	`number`	`10`	-; ≥ 1, ≤ 50
`maxTokens`	`number`	-	-; ≥ 1
`maxTotalTokens`	`number`	-	-; ≥ 1, ≤ 10000000
`timeoutSeconds`	`number`	-	-; ≥ 1, ≤ 3600
`toolNodeIds`	`array`	`[]`	-
`toolsJson`	`string`	`""`	-
`temperature`	`number`	-	-; ≥ 0, ≤ 2

Configuration help

systemPrompt Role and instructions: Describe its expertise, which tools to use, boundaries, and the expected response format.
userPrompt Task to complete: Accepts workflow expressions. When empty, uses the received input, including calls from another agent.
credentialId Credential: Credential required to access the external service.
model Model: Model identifier at the provider (e.g. gpt-4o, claude-3-5-sonnet).
maxTotalTokens Total token budget: Optional. Adds this agent’s input and output tokens. Reserves context before each request, caps output and stops if the provider omits usage or exceeds the budget. Tools calling other models have their own usage.
maxIterations Maximum iterations: Maximum agent/tool rounds before stopping.
maxTokens Max tokens: Maximum output tokens, including reasoning for applicable models. Truncated responses fail: increase this limit or shorten the request.
timeoutSeconds Timeout (seconds): Maximum time for one model call, including attachments. From 1 to 3,600 seconds; defaults to 120. Cancelling the workflow also cancels the call.
temperature Temperature: Lower values favor consistent answers. Leave empty to use the provider default; some models ignore this setting.
toolsJson Tool schemas (advanced JSON): Advanced: JSON array describing the tools connected to this agent. Use their exact names and set parameters (JSON Schema) to guide arguments. A tool must be connected to run.

Initial configuration

Initial catalog configuration example, to adapt before running. Keep secrets in credentials.

json

{
  "model": "",
  "fallbackModelNodeIds": [],
  "modelRoutes": [],
  "systemPrompt": "You are a helpful AI agent with access to tools.",
  "userPrompt": "",
  "agentMode": "tools_agent",
  "maxIterations": 10,
  "toolNodeIds": [],
  "toolsJson": ""
}

Verification

Check a response without tools first, then a request that requires the configured read tool. Compare the answer to the tool’s actual output and inspect steps, trace and usage. Also test missing data and approval rejection before production writes. Text claiming an action happened does not prove it ran.