The Complete Production SOP: How to Deploy and Run AcroForm Interactive PDF Form Filler in Autonomous AI Agents

---
name: "pdf-acroform-automated-filler"
description: "Inspect and populate interactive PDF AcroForms and XFA form fields programmatically."
metadata:
  author: "py-pdf"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "fill pdf form fields python"
  - "inspect acroform fields pdf"
  - "flatten completed pdf form"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

from pypdf import PdfReader, PdfWriter
import sys

def populate_acroform(input_pdf: str, output_pdf: str, form_data: dict, flatten: bool = True):
    reader = PdfReader(input_pdf)
    writer = PdfWriter()
    writer.append(reader)
    
    # Update fields across all pages referencing the root AcroForm
    for page in writer.pages:
        writer.update_page_form_field_values(page, form_data)
        
    if flatten:
        for page in writer.pages:
            for annot in page.get("/Annots", []):
                obj = annot.get_object()
                if obj.get("/Subtype") == "/Widget":
                    # Set read-only bit flag (bit 1) to lock fields
                    obj.update({b"/Ff": 1})
                    
    with open(output_pdf, "wb") as f_out:
        writer.write(f_out)

if __name__ == "__main__":
    print("pypdf engine ready")

import json
from pypdf import PdfReader

def extract_form_schema(pdf_path: str) -> dict:
    reader = PdfReader(pdf_path)
    fields = reader.get_fields()
    if not fields:
        return {}
    return {
        name: {
            "field_type": str(meta.get("/FT")),
            "default_value": meta.get("/V"),
            "field_flags": meta.get("/Ff")
        }
        for name, meta in fields.items()
    }

if __name__ == "__main__":
    schema = extract_form_schema("templates/sample_w9.pdf")
    print(json.dumps(schema, indent=2))