Document Generation for AI Agents with BlackStork #
AI agents are increasingly capable of complex reasoning, data synthesis, and API interaction. However, the final step of an agentic workflow - delivering those insights to a human user in a structured, professional document - remains a persistent challenge.
While future iterations of foundational models may eventually master complex layout and typography natively, relying on current LLMs to output raw, styled HTML or PDF files often leads to inconsistent results. BlackStork addresses this by providing a dedicated, deterministic presentation layer for your AI workflows.
If your team is actively building agentic workflows and requires reliable document generation, we are currently onboarding teams to our Design Partner program. Apply for early access here.
The structural and formatting bottleneck #
When agents attempt to generate final reports directly, two primary operational issues emerge:
Structural unpredictability - agents can hallucinate or inadvertently omit required sections of a report. If a compliance document requires five specific data tables and a mandatory disclaimer, an LLM might occasionally skip one. This forces human reviewers to read the entire document simply to verify the structure is intact, negating the time saved by the agent.
Formatting instability - generating raw HTML/CSS via a prompt often results in broken layouts or unclosed tags. Falling back to simple Markdown brings stability of the output, but sacrifices rich styling - corporate branding, page control, and complex data presentation.
Predictable structure and native formatting #
BlackStork solves this by strictly separating the agent’s reasoning from the document’s presentation. Instead of asking the agent to format a document, you ask the agent to supply structured data to a BlackStork template.
This approach provides two distinct benefits:
- predictable structure - templates act as rigid blueprints, with built-in data requirements and data mutations. They guarantee that all necessary blocks, disclaimers, and data fields are present in the final output. Human reviewers can trust the structure of the document and focus their time solely on validating the content generated from the data provided by the agent.
- reliable formatting - the BlackStork engine natively handles compiling the data and content into standardized Markdown, HTML, and PDF documents, consistent every time. Built-in sharing capability allows agents to create document URLs the users can immediately disseminate.
Equipping agents with BlackStork MCP #
To make this architecture seamless for developers, the BlackStork SaaS platform provides a Model Context Protocol (MCP) server. This equips your agents with specific tools to programmatically validate templates and render documents.
The BlackStork MCP exposes four core tools to your agent:
list_blocks- retrieves the catalog of available BlackStork template blocks and their required input schemas. Agents run this before drafting to understand which block types are permitted.list_template_docs- retrieves the catalog of available BlackStork template documents in your environment. These templates act as the entry point for rendering final documents.draft_and_validate_template- submits a proposed template for a dry-run validation. If the structure is invalid, it returns an array of errors, allowing the agent to safely self-correct and retry until the template is fixed.render- triggers the rendering of a specific template. It accepts a template ID and an inputs JSON object matching the template’s requirements. This synchronous tool returns a Markdown preview and, if requested, a secure public share URL.
Agent workflows #
With these tools available in their context, agents typically follow one of two structured workflows:
1. Creating a new template #
When tasked with building a new reporting template, the agent executes list_blocks to understand the available components. It then composes the template structure and passes it to draft_and_validate_template. By reading any returned validation errors, the agent loops through corrections until the engine returns a valid status.
2. Rendering and sharing #
For routine operational tasks, the agent retrieves the schema of an existing template and constructs the required JSON input payload. It executes the render tool and uses the returned Markdown preview to silently verify the data is correct. Finally, the agent presents the generated share_url to the user, providing immediate access to the fully formatted PDF or HTML document.
Example: An autonomous pentesting agent #
To show this separation of concerns in practice, we revisit the architecture from our previous post Building an Automated Pentest Report Template with BlackStork.
During an engagement, offensive security teams generate a massive amount of unstructured data: raw Nmap scans, Burp Suite logs, Slack conversations, and free-form scratchpad notes. Historically, a consultant would spend days manually translating this mess into a structured client deliverable. Instead, we can feed this unstructured data to an AI agent and have it drive a BlackStork template.
Our pentest template requires a hybrid data model consisting of two separate inputs:
- The machine data - a strict OWASP PTRS schema containing the raw vulnerabilities (CVSS scores, finding IDs, affected assets).
- The human context - a custom, STIX2-inspired schema that maps the narrative attack chain (Tactics, Techniques, and the step-by-step kill chain logic) which a flat vulnerability list cannot capture.
The agent’s role (reasoning) #
The agent analyzes the raw scan results and unstructured consultant notes. It maps the technical findings into the rigid OWASP PTRS JSON schema. It then synthesizes the conversational logs and scratchpad notes to generate the STIX2-inspired attack narrative data, effectively translating scattered thoughts into a logical kill chain and remediation roadmap.
BlackStork’s Role (presentation) #
The agent does not attempt to format this data into a PDF. Instead, it packages both JSON data blobs into a single payload and calls the BlackStork render tool. BlackStork ingests the data, injects it into the template, renders designated tables and text blocks, applies the predefined HTML/CSS formatting rules, and returns a share URL to a branded, customer-ready PDF.
The agent successfully delivers a complex, multi-page document entirely on its own, with zero manual formatting required.
Next steps #
By delegating document generation to a dedicated engine, your agents can focus entirely on data analysis, while your stakeholders receive consistent, premium reports.