Workflow Overview
What is a Workflow?
Workflows are the core feature of Zotero Agents, allowing you to combine multiple skill steps into automated processing pipelines. A Workflow defines a complete task: from receiving input, processing data, to producing output.
Workflow Structure
workflow.json (manifest file)
├── manifest: declares metadata, version, name
├── parameters: defines configurable parameters
├── inputs: defines input types (attachments, items, notes, etc.)
├── validateSelection: declarative input validation and filtering
├── hooks: JavaScript hook scripts (preflight, build requests, apply results)
└── provider: specifies the required backend type
Input Unit Types
| Type | Description |
|---|---|
attachment | Attachment files of an item |
parent | Parent item of the selected item |
note | Note item |
workflow | Batch scope |
Hook System
Workflows can run custom JavaScript scripts at various stages of execution:
- validateSelection: Declaratively filter and validate inputs before JavaScript hooks run
- preflight: Inspect the resolved input unit, attach execution context, skip, short-circuit to
applyResult, or expand one input into multiple request units - buildRequest: Build the request content sent to the backend
- normalizeSettings: Normalize user settings
- applyResult: Apply the results returned by the backend to Zotero
Three Execution Backends
Workflows can be executed through three backend types:
| Backend | Request Type | Use Case |
|---|---|---|
| Skill-Runner | skill.run.v1 | General skill execution, supports interactive mode |
| ACP | acp.skill.run.v1 | Skill execution via ACP backend |
| Generic HTTP | generic-http.request.v1 | HTTP API calls |
Official Workflow Package
Official Workflows are published and installed as standalone packages, decoupled from the plugin itself. Installation methods:
- Right-click menu → Zotero Agents → 📦 Install Official Workflow Package
- Click Install Official Workflow Package in Preferences
Official packages support three update channels: stable / beta / dev. The plugin automatically checks for updates on startup.
Official Workflows
The plugin includes a series of official workflows, grouped by function:
📚 Literature Analysis Toolkit
| Workflow | Purpose | Input | Backend | Docs |
|---|---|---|---|---|
| Literature Analysis ⭐ | Generate digest, references, citation analysis from PDF/MD. Can cascade into tag regulation | Attachment | Skill-Runner | Details |
| Literature Metadata Curator | Query, correct and complete bibliographic metadata for a Zotero item | Parent item | Skill-Runner | Details |
| Literature Translator | Translate academic literature with glossary management and quality gates | Attachment | Skill-Runner | Details |
| Interactive Literature Explainer | Multi-turn dialogue with AI for deep literature understanding, with verified answers to prevent hallucination | Attachment | Skill-Runner | Details |
| Deep Reading | Generate structured deep reading HTML view with translation support | Attachment | ACP | Details |
| Literature Search & Ingest | Let the Agent search academic literature and ingest directly into Zotero | workflow | ACP | Details |
| Collection Collector | Select existing library literature for an existing collection from a declared scope | workflow | ACP | Details |
| Export/Import Literature Bundle | Export/import portable ZIP bundles of Zotero items with metadata, attachments, and notes | Parent item / workflow | No backend required | Details |
| Export Research Bundle | Auto-assemble a read-only Research Bundle for a paper project from existing library and Synthesis context | workflow | Skill-Runner | Details |
| Tag Auditor | Scan all library items against the controlled tag vocabulary and report compliance | workflow | No backend required | Details |
| Tag Bootstrapper | Interactively create a controlled tag vocabulary for a research domain | workflow | Skill-Runner | Details |
| Tag Regulator | Normalize tags based on a controlled vocabulary and infer new tags | Parent item | Skill-Runner | Details |
| Export/Import Notes | Export or import analysis notes with support for editing and re-importing | Parent item | No backend required | Details |
🛠️ Utilities
| Workflow | Purpose | Input | Backend | Docs |
|---|---|---|---|---|
| MinerU PDF Parsing | Call MinerU service to parse PDF into Markdown | Attachment | Generic HTTP | Details |
| Topic Synthesis | Three-step pipeline to create topic synthesis analysis and reports | workflow | ACP | Details |
| Manuscript Literature Framing | Generate Introduction / Related Work LaTeX drafts | workflow | ACP | Details |
🔧 Debug Tools
| Workflow | Purpose | Backend | Docs |
|---|---|---|---|
| Debug Probe | Workflow system development testing and diagnostics | Skill-Runner | Details |
Next Steps
- Workflow Invocation & Configuration
- Backend Configuration — Detailed instructions for configuring backends