How to configure an AI Agent to save time

The most frequent question for people arriving at Pipefy is not "what does an AI Agent do". It is "how do I configure one for my process now". This article answers exactly that: from accessing the screen to the first agent running in production, with a concrete example any team can replicate.

The use case chosen is request triage by category and urgency. It is the most universal: it works for HR, procurement, IT and operations. It requires no external documents and no advanced configuration. The result appears on the card immediately after the first run.
 

📖  What you will do here:

Before you start: prepare the pipe

An AI Agent operates on fields that already exist in the card. Before creating the agent, confirm that the pipe has the fields it will read and the fields where it will write the result.

For the triage example, the pipe needs:

Input fields (what the agent will read):

• Request description — long text field where the requester explains the request

Output fields (where the agent will write the result):

• Category — select field with your process options (e.g. IT, HR, Finance, Operations)

• Urgency — select field with the options: High, Medium, Low

Step 1: access the AI Agents screen

In the pipe header, click AI Agents. If it is the first time, the screen will be empty. Click New AI Agent in the top right corner.

Step 2: define the name and description

The first screen asks for a name and description. The Description field is required and is not just organizational: the AI uses this text to understand the agent's purpose and improve the quality of the responses.

For the triage example:

Name: Request Triage

Description: Analyzes the request description and automatically classifies it by category and urgency level to speed up routing by the team.

Step 3: configure the Knowledge

The Knowledge tab defines what the agent knows beyond the card itself. For the triage example, there is no need to add anything: the agent will operate only with the content of the description field.

Two cases where it is worth adding knowledge:

• You want the agent to classify based on company-specific criteria (e.g. an internal policy in PDF)
• You want the agent to consult data from another pipe before making the decision (e.g. request history from the same requester)

Step 4: configure the Behavior

The behavior is the core of the agent. It has three parts: the trigger, the instruction and the actions.

4.1 Choose the trigger

The trigger defines when the agent will act. For triage, the ideal moment is the card's arrival in the first phase of the pipe, when the description has already been filled in by the requester.

Recommended trigger: When a card enters a phase — select the initial phase of the pipe.

4.2 Write the instruction

The instruction is what the agent will follow to make the decision. It is written in natural language, but it needs to be precise enough to generate a consistent result.

Four principles that define the quality of the prompt:

Start with an action verb. It is clearer to say "Analyze" or "Classify" than "I want you to understand".

Use dynamic fields, not fixed text. Instead of typing the field name manually, use the / bar or the + button to insert the field as a dynamic variable. This ensures the agent always reads the real content of the card.

Instruct both paths. Say what to do when the condition is met and when it is not. Agents without an instruction for the negative path frequently take no action.

Use examples inside the prompt when the criterion is subjective. "Classify as High Urgency if the requester mentions a deadline under 24 hours or immediate financial impact" is more effective than "classify by urgency".

Example instruction for the triage case:

Analyze the field [Request Description] and do the following:1. Classify the request into one of the categories: IT, HR, Finance or Operations.   If it is not possible to determine the category, use "Other".2. Set the urgency level:   - High: request mentions a deadline under 24 hours, immediate financial impact or operation shutdown.   - Medium: request mentions a deadline of 2 to 5 days or moderate impact.   - Low: request does not mention a deadline or the deadline is longer than 5 days.Update the field [Category] and the field [Urgency] with the determined values.

4.3 Define the actions

The actions tell the agent what to do with the result of the analysis. For the triage example, the action is one: Update card fields.

In the actions panel, select Update card fields and map:

• Category field → value determined by the agent
• Urgency field → value determined by the agent

Step 5: save and activate

After configuring the trigger, instruction and actions, click Save in the bottom right corner. The agent becomes active immediately. The next time a card enters the configured phase, it will run the analysis.

✅  Agent active. From this moment on, every card that enters the initial phase will have the Category and Urgency fields filled in automatically.

Step 6: monitor the first results

In the first runs, open the cards where the agent acted and check the Activities tab. It shows what the agent did, field by field, with the value that was written.

If the result is not what you expected, the adjustment path is almost always the same:

• Vague or incorrect result: the instruction needs more context or examples
• Field not filled in: check whether the dynamic field was inserted as a variable, not typed manually
• Agent did not run: check whether the trigger is pointing to the correct phase and whether the card actually entered it after activation

Before moving on, confirm that you have:

☐  Input and output fields created in the pipe with descriptive names

☐  The agent's name and description filled in specifically

☐  The trigger pointing to the moment when the information is already available in the card

☐  An instruction with an action verb, dynamic fields and criteria for both paths (positive and negative)

☐  The first cards monitored in the Activities tab after activation