Calculations & Analysis is an advanced capability you can enable in Pipefy's new AI Agents. With this feature activated, your digital agent is no longer limited to the static knowledge of a language model; it gains the ability to write small blocks of code at runtime within an isolated and secure environment (sandbox).
This allows the agent to solve complex equations with absolute mathematical precision, cross-reference data, execute deterministic compliance validations, and structure raw data extracted from documents — all without you needing to write or manage a single line of code. The agent reads your instructions in plain language, generates the programming logic in the background, runs the calculation, and
automatically fills the card fields (or executes other configured actions).
Audience and Availability
👤 Audience: Pipe Administrators (Pipe Admins)
🔐 Availability: Available on all Pipefy plans
What this capability solves
Traditionally, generative AI models (LLMs) are prone to hallucinations when subjected to complex mathematical operations or advanced logical rules. Activating the Calculations & Analysis capability transforms your agent into an exact digital worker, resolving:
Mathematical errors and hallucinations: Ensures total accuracy when summing invoices, conversion rates, applying penalties, and allocating cost centers.
Complex business logic (Long Tail): Replaces auxiliary external spreadsheets or expensive custom integrations with rules described in plain text.
Strict deadline calculations: Executes calendar operations (e.g., counting remaining business days for an SLA, excluding local holidays and weekends) flawlessly.
File structuring: Transforms disorganized or tabular data from attached PDFs and images into clean values ready to populate specific fields.
Before you start
You must have Pipe Admin permissions to create and configure AI Agents.
Have your business rules clearly written out. The agent will interpret your text instructions to build the logical execution scripts.
Step-by-step: Configuring the AI Agent with Calculations & Analysis
Creating and setting up your calculation-supported agent is divided into three main sections within the AI Agents panel: Create, Knowledge, and Behaviors.
Step 1: Initializing the Agent
Access the pipe where you want to deploy the analytical agent.
In the pipe header (top menu, right next to your pipe's name), click the AI Agents button.
On the digital agents management screen, click the New AI Agent button, located in the top right corner.
In the Create tab, enter a clear Name for your agent (e.g., Reimbursement Audit Agent) and a detailed Description.
❗ Attention: Filling out the Description field is mandatory, as Pipefy's intelligence uses this initial context to optimize the agent's decisions and performance.
Step 2: Defining the Knowledge Base (Optional)
Move to the Knowledge tab.
If your agent needs to consult fixed tables, corporate PDF policies, or records from other databases to support its calculations, add them here as secondary context sources. If it will only compute data natively from the card itself, you can skip this step.
Step 3: Activating the Capability and Behaviors
Click the Behaviors tab and select Add behavior.
Define the Trigger that will dictate when this agent behavior should run (e.g., Every time a card is moved to the Triage phase).
In the behavior configuration panel, locate the Capabilities section and check the box or toggle corresponding to Calculations & Analysis.
In the main instructions field (Prompt), write descriptively and in detail what logical or mathematical rule the agent must execute.
Example: "Take the total amount informed in the card, check if it exceeds the ceiling of the cost center
@Cost Center. If it does, calculate the excess percentage and change the status to review."You can type
/or click the+button to insert dynamic information extracted from your card's fields (variables).
Right below, in the behavior actions area, define what the agent should do with the logical results. Configure field mapping by clicking Select the fields to return the results to point out where the calculated answers (values, structured tables, reports) should be saved on the card.
Click Save to activate the behavior and put your AI Agent into production.
Real-World Use Case Examples
1. HR Compliance and Multi-factor Validation
Scenario: Validate vacation requests in compliance with labor laws.
How to instruct the Agent: In the behavior block, describe the rule: "Verify if the start date is at least 30 days from today. Check if the employee's vacation balance (
@Vacation Balance) covers the requested days and ensure the period is not less than 14 days. Return if the request is Valid or Invalid and list the violated rules."
2. Item Extraction and Purchasing Reconciliation
Scenario: Read Invoices and populate Pipefy records without manual data entry.
How to instruct the Agent: Activate document reading and describe: "Interpret the attached Invoice. Identify all listed items, extract their unit values, multiply by the quantities, and confirm if the total sum matches the final invoice value. Insert the items structurally into the card's connected fields."
3. FP&A and Budget Variance Analysis
Scenario: Audit monthly financial reports against the planned budget.
How to instruct the Agent: "Open the attached PDF report. Compare the actual expenses line with the planned budget line (
Budget vs Actual). Calculate the absolute and percentage variance of each sector and sort the results from highest to lowest deviation, pointing out which ones exceeded the 10% margin."
When NOT to use this capability
Calculations & Analysis focuses strictly on logical paths driven by rules and exact math. Do not spend processing power activating it if:
The agent's function is purely creative or conversational (e.g., drafting cordial thank-you emails, summarizing long textual interactions, or categorizing the emotional tone of messages). The agent's native language model already does this perfectly without needing the code execution engine.
The operation only requires fetching raw data from an external system or reading a static article from the knowledge base and pasting it into the card, without applying any transformation, advanced filter, or arithmetic operation on the found information.
Validation and Testing Checklist
Before opening the agent for the team to use in daily operations, complete the following protective checklist:
[ ] Lower Limits and Errors Test (Edge Cases): Deliberately create a card with zeroed data, negative values, or empty date fields to validate if the logic developed by the agent knows how to handle exceptions and point out errors without breaking the automation.
[ ] Variable Nomenclature Audit: Ensure that all dynamic field tags inserted into the instructions (e.g.,
@Order Value) remain mapped and share the exact same name in the form. If you change a field's name in Pipefy, remember to update the agent's behavior prompt.[ ] Use of Field Descriptions: A good practice to refine the filling of complex fields is to use the native description field in the Pipefy form. The agent reads the field notes and descriptions as extra context when understanding where to inject each generated data point.
[ ] Safe Staging Strategy: During the first week, do not map the agent to perform direct critical actions (such as instantly approving payments). Route the agent's calculation outputs to an "AI Review" field and use a human audit phase before moving the card forward.
Troubleshooting Common Issues
The agent executed a calculation or applied a business rule incorrectly
How to fix: Go to the behavior settings and refine the instructions written in natural language. The safest way to guide the internal code engine is to use practical examples. Insert fixed scenarios within the text itself (e.g., "If the input is X, the result should be Y. If the input is W, the result should be Z"). This guides the code generator with extreme precision.
Card fields do not update after the agent runs
How to fix: Access the Pipefy side menu, go to Automations, and open the Logs tab to check your agent's execution history. Check if there is any type compatibility error (e.g., the agent tried to inject a long explanatory text into a field formatted strictly to receive "Number" or "Currency"). Also, ensure that the labels mapped in Select the fields to return the results faithfully correspond to the active fields.
Error when processing or reading document/image attachments
How to fix: Make sure the card files are strictly in PDF, PNG, or JPG formats. Also, verify if the execution volume limits were exceeded (more than 30 pages per PDF or more than 30 images per card).