Document Generation: Dual-Backend Workflow (Unicode-Safe)

When to Use

Default Approach: Lightweight Direct Execution (Recommended for 90% of tasks)

For most document generation tasks, use direct write_file + run_shell without shell_agent:

• Generating documents in standard formats (.docx, .pdf, .html) from Markdown
• Content is straightforward with minimal special characters
• You already know the pandoc/ReportLab commands needed
• Quick single-format or multi-format output is needed

Fallback Approach: shell_agent Delegation (For Complex Scenarios Only)

Use shell_agent delegation only when:

• Automated fallback handling between backends requires complex logic
• Dynamic content generation needs programmatic decision-making
• You need to capture and analyze error messages for intelligent retry logic

When shell_agent May Be Useful (Optional)

Only consider shell_agent delegation for:

• Complex error recovery requiring automated backend switching
• Dynamic workflows with conditional branching based on generation results

Core Technique

For simple tasks (default): Use direct write_file + run_shell with pandoc or ReportLab (no shell_agent needed)

For complex tasks requiring fallback logic: Split the workflow into discrete, observable steps with two PDF generation paths:

Path A (Pandoc): Best for Markdown-to-PDF conversion with rich text formatting Path B (ReportLab): Best for programmatic PDF generation without LaTeX dependencies

Workflow steps:

1. Content creation → Use write_file to create source document (Markdown)
2. Choose PDF backend → Decide between pandoc (rich formatting) or ReportLab (programmatic control)
3. Unicode handling → Apply sanitization for pandoc; ReportLab handles Unicode natively
4. Format conversion → Use run_shell with appropriate commands for each format
5. Verification → Check output files exist and are valid

⚠️ Backend Selection Guide