# AI Agent - Workflow node | Docs - nodulz

Source: https://nodulz.com/docs/nodes/ai_agent

Language: en

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:

1. Prepare an accessible model credential and choose a model available to that account.
2. 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.
3. Use the manual payload `{ "question": "Rephrase in one sentence: our meeting has been moved to tomorrow." }`.
4. Set `userPrompt` to `{{ input.question }}` and `systemPrompt` to `Reply in English, in one sentence, without adding facts.`.
5. 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](/docs/executions#agent-tool-approval). Memory is optional: add it only if several exchanges need to share context.

## Credentials and prerequisites

- [Create and configure the credential : ai-model](/docs/credentials/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](/docs/credentials) 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

| Setting | Purpose and guidance |
| --- | --- |
| `systemPrompt`<br>Role and instructions | Describe its expertise, which tools to use, boundaries, and the expected response format. |
| `userPrompt`<br>Task to complete | Accepts workflow expressions. When empty, uses the received input, including calls from another agent. |
| `credentialId`<br>Credential | Credential required to access the external service. |
| `model`<br>Model | Model identifier at the provider (e.g. gpt-4o, claude-3-5-sonnet). |
| `maxTotalTokens`<br>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`<br>Maximum iterations | Maximum agent/tool rounds before stopping. |
| `maxTokens`<br>Max tokens | Maximum output tokens, including reasoning for applicable models. Truncated responses fail: increase this limit or shorten the request. |
| `timeoutSeconds`<br>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`<br>Temperature | Lower values favor consistent answers. Leave empty to use the provider default; some models ignore this setting. |
| `toolsJson`<br>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.

See also : [Expressions and data](/docs/expressions), [Executions](/docs/executions), [Node catalog](/docs/nodes).

## Explore further

- [Features - nodulz](https://nodulz.com/product/overview)
- [Node catalog - nodulz](https://nodulz.com/product/catalog)
- [MCP server - nodulz](https://nodulz.com/product/mcp)
- [Pricing - nodulz](https://nodulz.com/pricing)
- [Use cases and workflow automation - nodulz](https://nodulz.com/use-cases)
- [Choose what your workflows can do. - nodulz](https://nodulz.com/compare)
- [Documentation - nodulz](https://nodulz.com/docs)