🛠 Connecting AI Agents with External Tools and Data

UpBrains AI Agent Builder enables you to define and run intelligent automation workflows through configurable AI Automation Agents. Each agent has an Automation Flow—a sequence of steps including AI-powered decisions, data lookups, integrations, approvals, and inter-agent orchestration.

In this guide, we will review how you can call (trigger) your AI Agent manually or programmatically from external sources, and how to access and fetch data and results from external tools, systems and APIs in your agent flow. 

This technical guide for the UpBrains AI Agent Builder provides a comprehensive walkthrough for configuring AI Automation Agents using the drag-and-drop interface. It outlines:

(1) How to trigger agents externally using webhook URLs in both asynchronous (default) and synchronous modes, including returning structured responses with a ‘Return Response’ action.

(2) How to integrate external APIs through configurable HTTP requests supporting GET, POST, PATCH, and PUT methods. 

(3) How to read from and writing to external data sources, including tools like Google Sheets, Microsoft Excel 365, file storage systems (Google Drive, OneDrive, Dropbox, Amazon S3), databases (MySQL, PostgreSQL), and SFTP/SMTP services. 

(4) How to modularize your agent flow design by calling sub-agents and subflows, enabling modular design and the option to pause the parent agent flow until the sub-agent completes. 

(5) How to manage asynchronous calls to external APIs and tools and return the result to Agent flow asynchronously using resume links, pausing the agent with a ‘Wait for Approval’ step, and resuming execution upon external confirmation via GET or POST calls. The guide emphasizes no-code configuration, best practices, and compatibility with standard enterprise integrations.

Let’s begin.

🔗 1. Calling an Agent from External Tools

Agents can be triggered externally through calling their Webhook Live URL.

🧷 Defining an Agent with a Webhook Trigger

1. In your Agent Flow, add a trigger node.

2. Select Webhook Trigger from the list of available triggers.

3. The system generates a Live Webhook URL (e.g., https://agents.upbrains.ai/v1/webhoos/{id}).

⚡ Asynchronous Webhook Calls (Default)

• The default behavior of calling an agent’s webhook is asynchronous.

• The webhook returns a 200 OK response immediately after being called as an acknowledgment.

• The Agent flow continues to execute in the background.

• Use this when the caller doesn't need to wait for the outcome (e.g., fire-and-forget notifications).

🔄 Synchronous Webhook Calls

• Append /sync to the URL:
  https://agents.upbrains.ai/v1/webhoos/{id}/sync

• In this model, the caller is expected to wait for the Agent to complete and return a result.

• To send a custom response back:

  1. Add the “Return Response” action under Webhook tools in your flow.

  2. Place it at the end of your Agent flow or right after critical logic when the response is ready to be sent back.

  3. Define the data you wish to return (e.g., as a JSON response).

🌐 2. Calling External Tools from an Agent Flow

Use the HTTP Tool to make calls to any REST-enabled external system.

🔧 Configuring an HTTP Call Step

1. Drag the HTTP Request action into your flow.

2. Choose the HTTP method: GET, POST, PATCH, or PUT.

3. Configure the following fields:

   • Endpoint URL (can include dynamic variables)

   • Headers (e.g., content type, auth tokens)

   • Query Params (for GET requests)

   • Request Body (for POST/PATCH/PUT)

4. Choose the response type (for GET method):

   • Text, JSON, HTML, etc.

   • Base64

   • Signed URL

📊 3. Reading and Writing Data from External Sources

UpBrains AI offers drag-and-drop integrations with common storage, spreadsheet, and database tools.

📈 Spreadsheet Integrations

Google Sheets

1. Add a Google Sheet action.

2. Authenticate your Google account.

3. Choose from actions like:

   • Find Rows

   • Update Row, …

     
     

Microsoft Excel 365

1. Add Excel 365 from the flow tool list.

2. Authenticate with your Microsoft account.

3. Available actions:

   • Read/write data into worksheets

   • Add/update/delete table rows

     
     

🗂 File Storage Integrations

Use these to fetch or store files like PDFs, CSVs, or documents:

• Google Drive, OneDrive, Box, Dropbox, Amazon S3

• Available steps:

  • Upload File

  • Download File

  • Search by Name

  • Read File Metadata

🔐 Other Protocols

• SFTP: Upload/download files using secure file transfer.

• SMTP: Send emails with file attachments.

🧮 Database Integrations

Use these tools to read data from external databases into your agent flow.

• Supported: MySQL, PostgreSQL

• Actions include:

  • Execute Query (e.g., SELECT, INSERT)

  • Insert/Update Records

Use variables in your SQL queries to make them dynamic based on prior flow steps.

🔁 4. Calling Subflows (Sub-Agents)

You can modularize your automation by invoking other AI agents as Subflows.

⚙ How to Configure a Subflows Call

1. Add a Subflow Call action.

2. Select the target Sub Agent in the Flow parameter of Subflows you want to invoke. See example Subflows step below. (Note: it should include a ‘Callable Flow’ trigger and should have been published to see it in the Flows list).

   
   

3. Pass input data using variable mappings.

4. Choose behavior:

   • ✅ Wait for result (Agent Flow pauses until Subflow completes)

   • 🚀 Fire and forget (continue without waiting)

5. If waiting for the result:

   • In the sub-agent (subflow) you should have a final Return Response action that returns the results back to the parent agent flow.

   • The response from the sub-agent becomes available in the ‘data’ variable in the output of the Subflow call for subsequent steps.

🕓 5. Waiting for an Asynchronous Call to Complete

When the external system needs time to process and return the outcome later, UpBrains AI supports pause-resume of the agent flows through actions called “Approval Link” (or Resume Link) and Wait for Approval (Wait to be Resumed). 

🧩 Step-by-Step Setup for Asynchronous Resume

Step 1: Make the External Call

1. Generate a resume link (through Approval Link action).

2. Use the HTTP Request action to trigger an external process.

3. Include a Resume Link in the payload:

   • Add “Create Approval Link” action before the HTTP step as mentioned in Step 1.

   • It generates a unique one-time-use URL.

Step 2: Pause Execution

1. After making the HTTP call, use the “Wait for Approval” action.

2. This pauses the Agent flow until the approval/resume URL is triggered.

Step 3: External Tool Calls the Resume Link

• Once the external system completes processing:

  • It should call the Resume URL using GET or POST.

  • Payload (if sent via POST) will be parsed and made available as a variable for the rest of the flow.

Step 4: Continue Execution

• The flow automatically resumes once the link is called.

• Use submitted payload fields in downstream logic (e.g., AI reasoning, condition checks, database inserts).

✅ Best Practices

• Use clear step names and comments in each node to document your logic.

• Group logic into modular subflows to encourage reuse.

• Use try-catch style branches to handle external call failures gracefully.

• Avoid long synchronous agents—prefer asynchronous mode for external system integration.

• Log and store relevant outputs for traceability and debugging.

🧩 Supported Step Types in Agent Flow Builder

This guide should equip you with everything needed to build robust, intelligent, and connected automation agents using UpBrains AI Agent Builder.