Key concepts

These are the ideas you will find on every NappAI screen. Once they are clear, the rest of the documentation is much easier to read.

Project and flow

A flow is an automation: a series of steps that receive information, do something with it and return a result. Each flow lives inside a project, and in practice the two words mean the same thing. The Projects screen gathers them all, organised in folders.

See Projects.

Components

A component is each of the steps of a flow. Each component does one thing: receive a message, ask an AI model, read a spreadsheet, send an email, decide which way to go…

In the editor you pick components from a panel organised by categories, such as Core, Data, A.I., Operations or Integrations. Each component has a settings panel with its fields.

See Add components. Each component has its own page in the Components section of this documentation.

Connections

Components are joined with connections. Each component has input points on one side and output points on the other; when you connect the output of one to the input of another, what the first produces goes to the second.

Only compatible points can be joined: the editor dims the others while you drag. That way the flow reads from left to right, in the order the information travels.

Flow inputs and outputs

Every flow starts with something that sets it off and ends in a result:

Inputs: a chat message (Chat Input), a text (Text Input), a call from another application (Webhook Input), a notice from a connected service, a phone call (Voice Agent)…
Outputs: the answer in the chat (Chat Output), a text (Text Output), a sent email, a new row in a spreadsheet, a document…

A flow can also run on its own, on the dates you choose, with the Scheduler.

AI models

A model is the artificial intelligence that understands and writes text. NappAI has a component for each model provider, such as OpenAI, Gemini or Anthropic. In each one you choose that provider’s credential and the specific model in Model Name.

A model can be used on its own, to answer a text, or connected to an agent so that it does the agent’s thinking.

Agents

An agent is a component that uses a model to resolve a request. Unlike a fixed step, the agent reads the request, decides what to do and, if you have given it tools, chooses which one to use and in what order before it answers.

The Agent component has two connection points at the bottom: Model, where you connect the model it uses, and Tools, where you connect its tools.

See Agent.

The agent’s instructions

The agent’s settings have two different texts:

Field	What it is	Example
System Prompt	The fixed instructions: who the agent is, what it must do, what information it has and what it must not do. They apply to every conversation.	You are the assistant of a furniture shop. Answer briefly and in the customer’s language.
User Prompt	The request at each moment. By default it is `{input}`, the slot that receives what comes in through the Input connection.	The question the customer types in the chat.

If the agent doesn’t answer as you expect, check the System Prompt first: the more concrete the instructions and the information you give it, the more reliable the answers.

Tools

A tool is a component the agent can use when it needs to: look up a spreadsheet, check the calendar, send an email, run another flow…

To give it one, connect the Tool point, at the top of the component, to the agent’s Tools point. The agent decides in each conversation whether to use it and with what data. In the component’s settings, each field has a button that hands it over to the AI (Defined by AI): the agent then fills it in from the conversation. The fields you don’t mark are set by you.

An agent can have several tools at once. Describe in the System Prompt when it should use each one.

Batch Mode

When a component receives a list, such as the rows of a spreadsheet, Batch Mode makes it process each item and return all the results together. You turn it on in the component’s settings; once on, the component receives the list through its Batch Input point and each field can take a fixed value (Fixed) or a piece of data from each item (Mapped).

See Process lists.

Credentials

A credential is the saved access to an external service: a model provider’s key, your Gmail account, a Telegram bot… You save it once and choose it in every component that needs it. Once saved, the key is not shown again.

See Credentials.

The playground

The Playground runs the flow from the editor so you see the result straight away. If the flow starts with a Chat Input, you use it like a chat. On the left you can see what each component received and returned.

See Test the flow in the playground.

Draft, version and publishing

What you edit on the canvas is the flow’s draft, and it is saved automatically. A version is a named copy of the flow at a given moment. Publishing means deploying a version: it is the one used by other applications, scheduled runs, connected channels and phone calls.

The playground always runs the draft. That way you can keep testing changes without affecting anyone already using the flow.

See Versions and publishing.

Executions

An execution is each time a flow runs. NappAI records what each component did in every execution, and you look it up in Executions Logs.

See Execution logs.

Environments

An environment is a named set of values you can link to a flow, for example the address of a service or a customer identifier. It lets you use some values while testing and others in production without changing the flow.

See Environments.