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

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

System instruction

This is the most important setting. 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.

Few-shot examples

Few-shot examples are sample conversation pairs that show the AI exactly what you expect. Each example has a User message and a Model response.

1. Scroll to the Few-Shot Examples section.
2. Click Add Example.
3. Type a sample user message on the left.
4. Type the ideal AI response on the right.
5. Add as many examples 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.1 Pro - Google's most capable model. Great for complex reasoning and long-form content.
• Gemini 3 Flash - Fast and cost-effective. Good for simpler tasks where speed matters.
• Other Gemini variants are also available.

OpenAI

• GPT-5.5 - OpenAI's newest frontier model, built for the most complex, professional-grade work.
• GPT-5.1 - Strong at coding and agentic tasks, with configurable reasoning effort.
• Earlier GPT-4o models remain available for lighter-weight or lower-cost tasks.

Anthropic Claude

• Claude Opus 4.7 - The most capable Claude model. Best 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, billed against your FormWise credits rather than a connected provider key. A good default when you want speed and don't need to configure an external API key.

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.5 or Claude Opus 4.7. If speed and cost matter more, go with a lighter model like Gemini 3 Flash, Claude 4.5 Haiku, or FormWise Instant.

Include chat history

This setting is available for chatbot Flows. When enabled, the AI receives the full conversation history so far - not just the latest message. This allows it to remember what was said earlier and respond in context.

Turn this on for conversational Flows where context matters. Turn it off if each message should be treated independently.

Show thinking

Some models can display their reasoning process before giving a final answer. When Show thinking in chat 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 attach tools that the AI can call on demand during its response. These are listed under the Tools section of the configuration panel.

The built-in tool toggles are:

• 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.
• Artifacts - The AI gets access to document, code, and image generation tools that produce artifacts alongside its text reply. Image generation and document creation can be toggled independently once Artifacts is on.
• Allow access to all Organization Flows - The AI can call any other published Flow in your organization as a sub-skill. Useful for routing or composition.

You can also add more advanced tools manually:

• MCP servers - Connect any MCP server to expose its tools to the AI. Used for custom internal systems or third-party MCP integrations.
• Composio toolkits - Add prebuilt connectors for hundreds of SaaS apps (Gmail, Slack, HubSpot, and more). See Composio.
• Skills and Functions - Reusable sub-workflows you have built. See Node Types.

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 Tools section. 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 enabled at the Flow level (not per Agent node) and 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.
• Pick the right voice and "vibe." Different Flows need different personas. See Voice Mode for voice selection and tuning.

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.

Input source

This controls what the AI receives as its input:

• Piped - The node automatically receives the output from the previous node in the workflow. This is the default and works well for most linear workflows.
• Custom - You write your own input template. This lets you combine data from multiple sources, reference specific variables, and format the input exactly how you want. Use the variable picker to insert references to input fields, state variables, or outputs from other nodes.

Output format

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, an Output 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

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 the node's Options section:

• 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.

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 Notebooks knowledge source 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.