File-Drop Triggers

​

Key Capabilities

• Cloud folder monitoring — Watch a Google Drive folder, OneDrive folder, or SharePoint library for new files and start a Run as each one lands
• Email attachment monitoring — Start a Run when an email arrives in Gmail or Outlook with an attachment, passing both the message and its files to the agent
• Duvo-hosted upload endpoint — Upload files programmatically via the Duvo API (sandbox upload), then start a Run with those files as input. Useful when an external system (a form, script, or pipeline) needs to push files to Duvo directly over HTTP
• Deduplication with Agent Memory — Track which files have already been processed so the agent never acts on the same file twice
• Multi-format support — Process PDFs, spreadsheets, images, Word documents, and other formats using the built-in Email Attachments Reader and Intelligent Document Reader connections
• Flexible response — Extract structured data, validate against business rules, write records to downstream systems, and flag anomalies for human review

​

How File-Drop Triggers Work

​

When to Use File-Drop Triggers

• Invoice processing — Vendors drop PDF invoices in a shared folder; the agent extracts fields and posts records to your accounting system
• Document validation — Suppliers submit compliance documents via email; the agent checks required fields and flags missing information
• Report ingestion — A third-party system exports CSVs to a shared drive nightly; the agent imports and transforms the data each morning
• Image and scan processing — Field teams photograph forms and upload to a shared folder; the agent reads and transcribes each image

​

How to Set It Up

​

Option A: Email attachment trigger (push, seconds latency)

1. Open your agent and go to Setup.
2. Enable the Gmail or Microsoft Outlook trigger.
3. Optionally add a sender filter to restrict the trigger to emails from known senders (see Sender-Scoped Email Triggers).
4. Add the Email Attachments Reader connection to extract data from PDF, Excel, image, and other attachment types.
5. Write your AOP to describe what to do with each attachment — extract fields, validate, write records.

​

Option B: Cloud folder polling trigger (minutes latency)

1. Open your agent and go to Setup.
2. Set a schedule of every 5 or 15 minutes (or whatever interval is appropriate for your workflow).
3. Add the relevant cloud storage connection (Google Drive, Microsoft OneDrive, or Microsoft SharePoint).
4. Enable Agent Memory and note a memory key such as processed_files where the agent will store the list of file IDs it has already handled.
5. Write your AOP to:
   • List all files in the target folder
   • Compare against processed_files in memory to identify new files
   • Process each new file
   • Add each processed file’s ID to processed_files in memory before finishing

​

Option C: Duvo-hosted upload endpoint (push, seconds latency)

1. Your external system calls POST /sandboxes to create a sandbox and receives a sandbox_id.
2. It uploads one or more files to POST /sandboxes/{sandbox_id}/files, passing each file as multipart form data with an Authorization: Bearer <api_key> header.
3. It calls POST /teams/{teamId}/runs with the sandbox_id and your agent ID to start the Run. The uploaded files are available to the agent at the path specified during upload.
4. Optionally, provide a human_request_webhook_url when calling POST /teams/{teamId}/runs. Duvo will POST to this URL whenever the agent reaches a Human-in-the-Loop step — that is, when it cannot complete processing automatically and needs a human to approve, reject, or supply information. The payload includes the run ID, request ID, request title and description, and a timestamp. Use the Respond to Human Request endpoint to resume the Run once the reviewer has responded.

• A Duvo API key — create one in Team Settings → API Keys. See Running Agents via API for authentication details.
• Your external system should handle retries and protect its webhook endpoint (for example, by validating a shared secret or token). Duvo does not validate signatures on requests sent to your endpoint.

API_KEY="dv_your_api_key"
TEAM_ID="your-team-id"
ASSIGNMENT_ID="your-assignment-id"
BASE_URL="https://api.duvo.ai/v2"

# Step 1 — Create a sandbox
SANDBOX_ID=$(curl -s -X POST "$BASE_URL/sandboxes" \
  -H "Authorization: Bearer $API_KEY" | jq -r '.sandbox_id')

# Step 2 — Upload the file
curl -X POST "$BASE_URL/sandboxes/$SANDBOX_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./invoice.pdf" \
  -F "path=/workspace/invoice.pdf"

# Step 3 — Start the Run
curl -X POST "$BASE_URL/teams/$TEAM_ID/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$ASSIGNMENT_ID\", \"sandbox_id\": \"$SANDBOX_ID\"}"

​

Worked Example — Vendor Invoice Processing

• Google Drive — list and read files in the shared folder
• Intelligent Document Reader — extract fields from PDF invoices
• Google Sheets — write extracted records
• Human-in-the-Loop — pause for review when a field is missing or out of range

​

Before You Start

• Invoice folder — A shared Google Drive folder where vendors drop invoices. Note the folder name or ID.
• Approved vendor list — A Google Sheet with a column of valid vendor names (for example, a sheet named “Approved Vendors” with a “Vendor Name” column). Optionally add an “ERP Vendor ID” column for downstream mapping. Note the sheet name and tab.
• Accounting spreadsheet — A Google Sheet where extracted invoice records will be written. Note the sheet name and column headers you expect (Vendor Name, Invoice Number, Invoice Date, Due Date, Line Items, Total Amount, Processed Date).
• Google Drive and Google Sheets connections — Connect Google Drive and Connect Google Sheets from the Connections page.
• Agent Memory enabled — You will enable this in Step 4; no pre-configuration needed.

​

Step 1: Create the agent

1. Click + Create Agent from your dashboard.
2. Select Use Agent Builder.

​

Step 2: Write your AOP

Check the Google Drive folder at [folder name or ID] for new files that have not been
processed before.

For each new file:
1. Read the file using the Intelligent Document Reader and extract:
   - Vendor name
   - Invoice number
   - Invoice date
   - Due date
   - Line items (description, quantity, unit price)
   - Total amount

2. Validate the extracted data:
   - Vendor name must appear in [your approved vendor list in Google Sheets / your ERP]
   - Invoice number must not already exist in [your accounting spreadsheet]
   - Total amount must be greater than 0 and below [your single-invoice limit, e.g. $50,000]

3. If all fields are present and pass validation:
   - Append a new row to the "Invoices" sheet with all extracted fields and today's date.

4. If any field is missing, unreadable, or fails validation:
   - Do not write the row.
   - Request human review. Title: "[Issue type] — [Invoice number or filename] — [Vendor name]".
     Include all extracted fields and the specific issue.
   - After the reviewer approves (with any corrections) or rejects, either write the corrected
     row or leave the invoice unprocessed and log the reason.

5. Record the file ID in memory under the key "processed_files" so it is not processed again.

​

Step 3: Add connections

• Google Drive — to list and read files in the shared folder
• Intelligent Document Reader — already available by default
• Google Sheets — to write invoice records and look up the approved vendor list
• Human-in-the-Loop — already available by default

​

Step 4: Enable Agent Memory

​

Step 5: Set a schedule

1. Click Schedule in the agent header.
2. Choose Custom and set an interval of every 15 minutes, or every hour if near-real-time processing is not required.
3. Click Add schedule to save.

​

Step 6: Test with a sample invoice

1. Upload a sample invoice PDF to the Google Drive folder.
2. Click Start Work to run the agent manually.
3. Confirm the fields were extracted correctly and the row was written to your spreadsheet.
4. Upload a second PDF with a missing field and verify the Human-in-the-Loop request is created.

​

Expected Results

• A new row for each valid invoice, with all extracted fields populated.
• No rows created for invoices with validation errors — those are held for review.

• A Human-in-the-Loop request for each invoice with a missing, unreadable, or anomalous field.

• The processed_files list grows with each Run. Files already processed are skipped even if they are still in the folder.

• A session log per scheduled Run showing which files were found, processed, and skipped.

​

Troubleshooting

​

New files are not being picked up

• Folder path: Verify the folder name or ID in your AOP matches the actual folder in Google Drive. Paste the folder URL into the AOP if the name is ambiguous.
• Memory conflict: If the processed_files list was corrupted or contains a wrong ID, clear the memory for this agent in Setup > Agent Memory and let it reprocess.
• Permissions: Confirm the Google Drive connection has read access to the shared folder, including folders owned by others. Re-authorize from the Connections page if needed.

​

The same file is processed more than once

• The processed_files key in Agent Memory is case-sensitive. Make sure your AOP writes the same file ID format that it reads when checking for duplicates.
• If Agent Memory was cleared, files previously processed will appear new on the next Run.

​

PDF extraction is incomplete

• Scanned PDFs: Low-resolution scans reduce extraction accuracy. Ask vendors to send native PDFs where possible.
• Multi-page invoices: Explicitly state in your AOP: “Read all pages of the document.”
• Non-standard layouts: Add two or three sample invoices to Files and reference them in the AOP as formatting examples.

​

Files in subfolders are missed

​

Take It Further

After writing the invoice row, check if the vendor has a preferred reviewer in [your spreadsheet].
If so, include their name in the Human-in-the-Loop request title.

After writing the invoice row, send a confirmation email to the vendor's address (extracted from
the invoice) with the subject "Invoice [number] received — processing in progress."

​

Related

• Event-Driven Triggers — Overview of all trigger types and the trigger matrix
• Scheduling Agents — Set the polling interval for cloud folder monitoring
• Agent Memory — Store processed file IDs to prevent duplicate processing
• Human-in-the-Loop — Handle anomalous invoices with approval gates
• Email Attachments Reader — Extract data from PDFs, spreadsheets, and images attached to emails
• Intelligent Document Reader — Parse unstructured PDFs from cloud storage
• Google Drive — Connect your Google Drive
• Microsoft OneDrive — Connect your OneDrive
• Microsoft SharePoint — Connect your SharePoint library
• Running Agents via API — Full API reference for the Duvo-hosted upload endpoint (sandbox creation, file upload, run start)