Configuring Agent Nodes

Agent nodes are where the AI does its work inside a Flow. Each one takes input, sends it to an AI model, and produces output that the rest of your workflow can use. This guide covers every setting in the Agent node configuration panel so you can get the most out of your Flows.

[Screenshot: An Agent node selected on the canvas with the configuration panel open on the right.]

Opening the configuration panel

Click on any Agent node in the workflow builder.
The configuration panel opens on the right side of the screen.
Work through each section below to set up the node.

System instruction

This is the most important setting, labelled Agent's Instructions in the panel. The system instruction tells the AI how to behave - its role, tone, rules, and goals. Think of it as the job description you hand to the AI before it starts working.

A good system instruction is specific and clear. For example:

You are a friendly customer support agent for an online shoe store. Answer questions about orders, returns, and sizing. If you do not know the answer, say so honestly and offer to connect the customer with a human agent.

Tips for writing system instructions:

Start with who the AI is and what it should do.
Include any rules or constraints (what it should avoid, tone of voice, length of responses).
Mention the format you want the output in if it matters.
The more specific you are, the better the results.

User's message

The User's Message field is what the node sends to the model as its input. Write it as a template and insert references to form answers, state variables, or other nodes' outputs by typing @. See Variables and Data Flow.

Response style

The Response Style slider sets the model's temperature, from Precise (0) to Creative (2). The default is 0.7. Lower values give more consistent answers; higher values give more varied ones.

Few-shot examples

Few-shot examples are sample messages that show the AI exactly what you expect. Each example is either a User message or an Assistant response.

Untick Include current conversation history. A History list appears.
Click + and choose User or Assistant to add a message.
Type the example content. You can switch a message's role from its header.
Add user and assistant messages in pairs, as many as you need.

These examples act as a guide. The AI will follow the patterns you set - matching the tone, format, and level of detail in your examples.

Model selection

Choose which AI model powers this node. FormWise supports models from several providers, each with different strengths:

Google Gemini

Gemini 3.7 Flash - Google's newest Flash model, strong at coding and agentic tool use.
Gemini 3.6 Flash - A strong Flash model for coding and agentic planning.
Gemini 3.1 Pro - Advanced reasoning for highly complex problems and long-form content.
Gemini 3 Flash and Gemini 2.5 Flash - Fast and cost-effective. Good for simpler tasks where speed matters.

OpenAI

GPT-5.6 Sol - The top tier of the GPT-5.6 family, for the most complex work.
GPT-5.6 Terra - The balanced GPT-5.6 tier: strong reasoning at mid-tier cost.
GPT-5.6 Luna - The fast, low-cost GPT-5.6 tier for everyday and high-volume tasks.
GPT-5.5 and GPT-5.1 - Earlier frontier models. GPT-5.1 is strong at coding and agentic tasks.
GPT-4o, GPT-4o Mini, and GPT-4 Turbo remain available for lighter-weight or lower-cost tasks.

Anthropic Claude

Claude Opus 5 - Anthropic's flagship for deep reasoning and long-horizon agentic work.
Claude Sonnet 5 - Near-Opus quality at Sonnet speed and cost.
Claude Opus 4.8, Claude Opus 4.7, and Claude Opus 4.6 - Earlier Opus models for nuanced, complex tasks.
Claude Sonnet 4.6 - A strong balance of speed and capability.
Claude 4.5 Haiku - The fastest Claude model. Ideal for quick, simple tasks.

FormWise Instant

An in-house model tuned for very fast responses. It runs on your FormWise credits only, so there is no provider key to configure. A good default when you want speed.

Usage-billed models

GPT-6 Astra and Claude Fable 5.1 are the most capable models from OpenAI and Anthropic. They only appear in the model picker for workspaces on usage-based billing, which is rolling out gradually.

How to choose: If you need the best possible quality and do not mind slightly slower responses, pick a top-tier model like GPT-5.6 Sol or Claude Opus 5. If speed and cost matter more, go with a lighter model like Gemini 3.7 Flash, GPT-5.6 Luna, Claude 4.5 Haiku, or FormWise Instant.

Include conversation history

The Include current conversation history checkbox is on by default. When it is on, the AI receives the conversation so far - not just the latest message. This allows it to remember what was said earlier and respond in context.

Leave it on for conversational Flows where context matters. Turn it off if each message should be treated independently, or if you want to supply your own few-shot examples instead.

Show thinking

Some models can display their reasoning process before giving a final answer. When Show thinking in chat (under Advanced > Options) is enabled, users can see how the AI arrived at its response.

This is useful for tasks where transparency matters, like analysis or decision-making. For most user-facing Flows, you can leave it off to keep responses clean.

Tools the Agent node can use

An Agent node is not limited to generating text - you can give it tools that the AI can call on demand during its response.

The AI Capabilities section has these built-in toggles. Each shows its credit cost per call:

Artifacts - The AI can produce artifacts alongside its text reply. On by default. Once it's on, two sub-toggles appear: Image generation & editing (with a picker for the image model) and Document creation (text, code, and spreadsheet documents).
Web Search - The AI can run live Google searches via the Serp API. Useful for current events, market data, or anything that depends on fresh information. Adds latency, so leave it off unless you need it.
Web Scrape - The AI can fetch a URL and read the page contents via Jina Reader. Pairs well with web search for follow-up reading.
Deep Research - Multi-step research: the AI plans queries, reads many sources, and compiles a cited digest. Its searches and page reads are not billed separately.

Below that, Connected Services adds external tools:

Composio toolkits - Prebuilt connectors for Gmail, Slack, HubSpot, and 1000+ more SaaS apps. See Composio.
MCP servers - Connect any MCP server to expose its tools to the AI. Used for custom internal systems or third-party MCP integrations.

Under Advanced > Options, Allow access to all Organization Flows lets the AI call any other published Flow in your organization. Useful for routing or composition.

The more tools an Agent node has access to, the more it has to think about. Add tools deliberately - a focused node with three good tools usually outperforms a kitchen-sink node with twenty.

Artifacts

Artifacts are rich outputs the AI can produce alongside its text reply - think generated documents, code files, images, or spreadsheets that show up in a side panel rather than getting buried in the chat transcript.

To enable them, turn on Artifacts in the Agent node's AI Capabilities section (it is on by default). The AI will then have access to artifact creation tools and decide when to use them based on the user's request.

Use artifacts when your Flow generates:

Long-form content (reports, articles, proposals)
Structured documents you want users to download or copy
Images, code snippets, or spreadsheets

For the full set of artifact types and how they render to end users, see Artifacts.

Voice mode

Chatbot Flows can run in voice mode - users speak to the Agent node and it speaks back, with live transcripts on screen. Voice mode is on by default for chatbot Flows on plans that include conversational voice (Pro and Agency). There is no setting for it in the Agent node; it shows up as a soundwave button next to the chat input.

When you turn voice mode on, the responses are streamed to a text-to-speech engine, and the user's mic input is transcribed in real time. The conversation history still works the same way as text chat - this is purely a different way to talk to it.

A few things to keep in mind when configuring an Agent node for voice:

Keep responses short. Voice replies that go on for paragraphs are tiring to listen to. Bias your system instruction toward concise answers.
Avoid markdown. Bullet points and headings sound awkward when read aloud. Tell the model to respond in plain prose.
Need a specific voice? Chatbot Flows use the default voice. To pick a voice and tune its delivery with a vibe, build an Agent instead. See Voice Mode.

For the full configuration, see Voice Mode.

Chat attachments

For chatbot Flows, users can upload files mid-conversation - PDFs, images, spreadsheets, and more - and the Agent node can read them as part of its reply. Attachments are available by default in chat Flows; there's no separate setting to turn them on, and no extra Agent node configuration is required.

Use chat attachments when you want users to:

Drop in a document and ask questions about it.
Share a screenshot and have the model describe or analyze it.
Upload a spreadsheet for the model to summarize.

See Chat Attachments for supported file types and configuration.

Output format

Click Advanced to expand the rest of the node's settings. Under Output Type, choose how the AI structures its response:

Text - The AI responds with free-form text. Use this for most content generation tasks, chat replies, and anything a user will read directly.
JSON - The AI responds with structured data in a specific format you define. When you select JSON, a Schema editor appears so you can describe the shape of the output - field names, types, and whether each field is required.

JSON output is the right choice when:

A downstream node needs to read specific fields (e.g. name, priority, category).
You are sending the result to an external system via a Webhook node that expects structured input.
You want to enforce a consistent shape every time, regardless of how the model phrases things.

JSON output is enforced at the model level when the provider supports it, so the response is guaranteed to parse. If you do not need structured fields, stick with Text - it is faster and more natural to read.

Output variable name

When the output type is JSON, an Output Variable Name field appears. Give this node's output a name so other nodes can reference it. For example, if you name the output summary, downstream nodes can access it by referencing that variable.

Pick a short, descriptive name that makes it easy to understand what the output contains. See Variables and Data Flow for how variables move between nodes.

Other options

A few more toggles under Advanced > Options:

Show thinking in chat - For reasoning-capable models, surfaces the model's intermediate thinking to the user. Useful for transparency in analysis Flows; usually off for production chatbots.
Hide response from chat - For chatbot Flows, runs the Agent node silently without showing its output to the user. Useful when the node's job is purely to set a state variable or trigger a downstream node.
Allow access to all Organization Flows - Lets the AI call any other published Flow in your organization.

Best practices

Start with the system instruction. Get this right first - it has the biggest impact on output quality.
Pick the right model for the job. You do not always need the most powerful model. Use faster, cheaper models for simple tasks and save the heavy hitters for complex reasoning.
Use JSON output when you need structured data. If the next step in your workflow needs to pull out specific fields, JSON makes that reliable.
Add few-shot examples when the AI is not matching your expectations. A couple of well-chosen examples can dramatically improve consistency.
Add tools deliberately. Each tool the node can call is one more decision it has to make. Less is usually more.
Enable web search only when needed. It adds latency, so only turn it on for tasks that genuinely require current information.

Troubleshooting

A few common issues and where to look:

The node isn't using my knowledge. Make sure the relevant Knowledgebase is attached to the Flow and that the system instruction tells the model to ground answers in it. See Knowledge Sources.
Responses are too long or too short. Tune the system instruction with explicit length guidance ("Answer in two sentences", "Aim for ~300 words"). Few-shot examples reinforce this.
The node ignores tools you attached. Add a sentence to the system instruction describing when to use each tool, and check that the tool name and description are clear.
JSON output is failing. Verify the output schema is complete (all required fields defined) and that your system instruction does not contradict it.
Voice replies sound awkward. Tell the model to respond in plain prose without markdown, and keep replies short.

For more, see Troubleshooting.

Next steps

Now that you know how to configure an Agent node, learn how data moves through your workflow in Variables and Data Flow, or explore the full set of node types in Node Types.

Configuring Agent Nodes

On this page