The typical workaround is to run the document through a separate OCR or extraction service, write glue code to map the extracted fields to your schema, handle the confidence issues, and then submit the result to your validation gate. And even after extraction, you often need to verify the extracted values against reference datasets — is this HS code valid? Is this vendor approved? Does this SKU exist in our catalog? That's another integration point, another system to maintain.

Today we're launching two features that solve both problems together: Rynko Extract and Lookup Tables.

Extract adds a Stage 0 to the Flow pipeline. Upload a file to a gate, and the AI extracts structured data from it before validation runs. Lookup Tables let you upload reference datasets — tariff codes, vendor lists, product catalogs — and query them directly inside your gate's business rules. Together, they turn a multi-system integration problem into a single pipeline call.

How Extract Works

When you enable Extract on a gate, the gate accepts both structured input (JSON, YAML, XML) and unstructured input (PDFs, images, Excel, CSV, plain text). Structured input skips extraction entirely — it goes straight to validation, no extraction credit consumed. Unstructured input passes through the AI extraction layer first, then the extracted data is validated against the gate's schema and business rules.

The key design decision was: one schema, not two. The gate's published schema serves as both the validation target and the extraction target. When the AI model extracts data from a document, it uses the gate's schema as a guide — field names, types, descriptions, required fields. There's no separate "extraction schema" to maintain. You edit the gate schema once, and both extraction and validation update together.

Per-Field Confidence Scoring

Every field that Extract returns comes with a confidence score — HIGH, MEDIUM, or LOW — along with a numerical score between 0 and 1. This isn't a binary "we found it or we didn't" signal. It tells you how reliable the extraction is for each individual field.

A clean invoice with a clearly printed invoice number in the header will get a HIGH confidence score of 0.95+. A handwritten note where the amount is partially obscured might get a LOW score of 0.3. The confidence scores are per-field, not per-document, so a single extraction can have high confidence on the vendor name but low confidence on the purchase order number.

We built three review modes around this. "Continue" accepts everything regardless of confidence — useful for high-volume, low-risk workflows. "Review" routes to a human reviewer when any field drops below your configured threshold or when required fields are missing. "Fail" rejects the extraction entirely if quality thresholds aren't met.

The review mode creates a human-in-the-loop workflow where the reviewer sees the extracted data alongside the source document, with confidence badges on each field. They can edit values, approve the extraction, or reject it. The edited data then continues through the validation pipeline — reviewer corrections are treated as the authoritative extraction result.

Schema Discovery and Zero-Cost Iteration

If you have a new document type and don't know what fields it contains, you can upload a sample file and let the AI analyze it. The AI returns a suggested JSON Schema with field names, types, and descriptions — a starting point you can refine.

The discovery pass stores the raw AI output as a "reference extraction" in S3. Every subsequent schema edit re-maps fields from this reference using a local field matcher — exact match, normalized match (snake_case to camelCase), description similarity, common aliases, and fuzzy matching. No AI calls, no credits consumed. You can iterate on your schema as many times as you want after the initial discovery, and the field matcher instantly shows you how the reference data maps to your updated schema.

This pattern — one AI call to establish the reference, then unlimited local iterations — makes it practical to experiment with schema design without worrying about API costs.

How Lookup Tables Work

A lookup table is a team-level key-value store. You create a table, populate it with entries (either one at a time via the API or in bulk via CSV/JSON upload), and then reference it in your gate's business rules using the lookup() function.

The simplest example is an existence check:

// Is this HS code in our tariff schedule?
lookup('hs_codes_us', hs_code) !== null

The lookup() function takes a table name and a key, and returns the stored value if the key exists, or null if it doesn't. Since values are stored as JSON, you can store rich objects and access their properties:

// Is this item restricted?
lookup('hs_codes_us', hs_code).restricted !== true

// Is the unit price within the expected range for this category?
lookup('price_ranges', product_category).max >= unit_price

// Composite key for duty rate lookup
lookup('duty_rates', hs_code + ':' + origin_country + ':' + destination_country) !== null

You can also use the fail() function for prescriptive error messages that tell agents exactly what went wrong:

lookup('vendors', vendor_name) !== null
  ? true
  : fail('Vendor "' + vendor_name + '" not in approved list. Check spelling or onboard new vendor.')

This works well with Gate Intelligence — agents that fail a lookup check get a clear, actionable error message instead of a generic "rule failed" response.

The Double-Blind Principle

One design decision worth explaining: lookup table data is not sent to the AI during extraction.

This might seem counterintuitive — wouldn't extraction be more accurate if the model knew the valid HS codes? In practice, the opposite is true. If you give an LLM a list of 5,000 valid codes and ask it to extract an HS code from a blurry scan, it will "correct" what it sees to match something in the list. Instead of honest extraction, you get confident guessing.

We separate the roles deliberately. The AI is a witness — it reports exactly what it sees in the document, with a confidence score for each field. The gate is the judge — it checks the extracted values against your business rules and lookup tables deterministically. The lookup table is the law — it defines what's valid.

This means an extraction might come back with hs_code: "8471.30" at HIGH confidence, and then the gate rule lookup('hs_codes_us', hs_code) !== null confirms it's a real code. Or the extraction returns hs_code: "8471.39" (an OCR misread), the lookup fails, and the run routes to human review where the reviewer can see both the extracted value and the source document side by side.

The separation preserves the integrity of both steps. The extraction quality isn't artificially inflated by reference data matching, and the validation is fully deterministic — no probabilistic reasoning in the judgment step.

Atomic Bulk Sync

For small reference datasets — approved vendor lists, product categories — adding entries one at a time through the API is fine. But HS code databases have tens of thousands of entries, and product catalogs can have hundreds of thousands.

Bulk sync handles this with a shadow-flip pattern. When you upload a CSV or JSON file, the system writes all new entries at a new version number while your gate continues reading from the current version. Once all entries are imported, a single database update atomically switches the active version. There's no moment where your gate sees partial data — it's either the old complete dataset or the new complete dataset.

POST /api/flow/lookup-tables/:tableId/sync
Content-Type: multipart/form-data

file: hs_codes_2026.csv
mode: replace

The sync runs asynchronously via BullMQ, and you can poll the status or check the sync history. Each sync records how many entries were received, imported, and skipped, along with the duration.

Key Normalizers

One problem that came up immediately during testing: HS codes. Some invoices format them with dots (8542.31.0000), some without (8542310000). Both are the same code. A vendor extracted as ACME CORP won't match a lookup table entry stored as Acme Corp. Port codes might come through as uslax instead of USLAX.

Rather than forcing users to pre-process their data or write normalizing wrappers around every lookup() call, we added key normalizers at the table level. Each lookup table can specify a normalization strategy that's applied automatically — both when entries are stored and when keys are queried.

POST /api/flow/lookup-tables
{
  "name": "hs_codes_us",
  "keyNormalizer": "strip_dots",
  "keyDescription": "10-digit HTS code",
  ...
}

With strip_dots, the expression lookup('hs_codes_us', '8542.31.0000') matches a stored key of 8542310000 because both are normalized to 8542310000 before comparison. The original key is preserved for display — you still see 8542.31.0000 in the UI — but matching uses the normalized form.

Seven normalizer types are available:

The normalization happens at write time — a normalizedKey column is pre-computed alongside the original key and indexed for O(1) lookups. This means even tables with millions of entries don't pay a performance penalty for normalization. Changing the normalizer on an existing table triggers a background recomputation of all normalized keys.

It's a small feature, but it eliminates an entire class of false validation failures that would otherwise require custom expressions or data cleansing pipelines.

The Pipeline Orchestrator

Behind both features is a pipeline orchestrator built as an independent package (@rynko/pipeline-core). It's a data-driven stage router — the pipeline is defined as an ordered array of stage definitions, and the orchestrator walks the array to determine what comes next. Adding a new stage to the pipeline is adding one entry to the array. Reordering stages is moving the entry.

The orchestrator is framework-agnostic — zero dependencies on NestJS, Prisma, or any specific infrastructure. It takes a storage adapter interface and a logger interface, and that's it. The Flow module provides a thin NestJS wrapper that implements the storage adapter using Prisma and wires the stage executors to the actual services.

The validation stage is special: for direct JSON submissions, it runs synchronously in the HTTP request handler with zero database operations — the response returns in single-digit milliseconds. Adding Extract to the pipeline doesn't slow down the existing validation path at all.

Lookup resolution is Redis-cached with lazy loading — only keys that are actually queried get cached, with a one-hour TTL. For gates that don't use lookup() in any rule, there's zero overhead. All lookups across all rules are resolved in a single batch before any rule evaluation begins — no I/O during rule execution.

The Full Pipeline

Here's what a complete pipeline looks like for trade document processing:

1. Extract (Stage 0): Agent uploads a commercial invoice PDF. The AI extracts vendor name, HS codes, line items, quantities, unit prices, total amount, origin country, destination country.

2. Validate (Stage 1): Gate rules check the extracted data:

   • Schema validation: required fields present, correct types

   • Business rules: total_amount === sum of line item amounts

   • Lookup checks: lookup('hs_codes_us', hs_code) !== null for every line item

   • Lookup checks: lookup('approved_vendors', vendor_name) !== null

   • Lookup checks: lookup('sanctioned_entities', vendor_name) === null (blocklist — must NOT be in table)

3. Review (if needed): Low-confidence extractions or failed lookup checks route to a human reviewer who sees the original document alongside the extracted data.

4. Deliver (Stage 2+): Validated data is delivered via webhook, or rendered into a standardized document via Rynko Render.

The entire flow is one API call from the agent's perspective. Upload a file, get back a run ID, poll for results. The agent doesn't need to know about extraction confidence scores, lookup table queries, or human review routing — the gate handles all of it.

What's Available

Extract and Lookup Tables are available now in founders preview. Extract comes with 100 free extraction credits per team. Lookup tables are included in your Flow tier, with limits scaling from 1 table and 1,000 entries on Free up to 25 tables and 10 million entries on Scale.

The extraction runs on Google Gemini 2.5 Flash for fast, cost-effective processing. SDK support covers Node.js, Python, and Java with submitFileRun() for gate pipeline integration. For agents that already have document content as text, text-based extraction is available via MCP tools. Lookup table management is available through the REST API, and the webapp UI for managing tables and entries is rolling out now.

If you're building agent workflows that start with documents and need to validate extracted data against reference datasets — tariff codes, approved vendor lists, product catalogs, sanctions lists — this is what we built it for. The docs are at docs.rynko.dev and we're at rynko.dev.

• Policy evaluation at 0.012ms latency.

• Ed25519 cryptographic agent identity with trust scoring.

• Four-tier execution rings with kill switches.

• Circuit breakers and chaos engineering for reliability.

• Adapters for 12+ frameworks including LangChain, AutoGen, CrewAI, and Google ADK.

• 6,100+ tests. MIT licensed.

This is the kind of infrastructure that the agentic ecosystem desperately needs, and Microsoft giving it away for free accelerates the entire space.

It also makes me more confident about the bet we've been making at Rynko, because the toolkit solves a genuinely hard set of problems that we don't solve — and it leaves room for the specific problem that we do.

What the Toolkit Does Well

The toolkit has four components, and each one addresses a real production concern that teams building agentic systems struggle with.

Agent OS is the policy engine. Every agent action passes through it before an execution. You define capabilities like which tools the agent can call, resource limits like token budgets, API call caps and content policies. It evaluates these at sub-millisecond latency — 72,000 policy evaluations per second for single rules, 31,000 for 100-rule policies. Custom policies can be written in OPA/Rego or Cedar, which means teams can reuse their existing policy infrastructure rather than learning a new DSL, a thoughtful design choice.

AgentMesh handles identity and inter-agent trust. Every agent gets an Ed25519 cryptographic credentials. Trust scores on a 0–1000 scale determine what an agent can do eg. a score of 900+ gets verified partner access, below 300 gets read-only. The communication between agents is encrypted through trust gates, and it bridges A2A, MCP, and IATP protocols. The trust scoring model is particularly well thought out, eg. new agents default to 500 and progress based on compliance history, which mirrors how you'd onboard a new team member with gradually expanding permissions.

Agent Runtime is the execution supervisor. It uses four privilege rings to isolate what agents can touch. Saga orchestration is used to coordinate multi-step operations. Kill switches terminate non-compliant agents and Append-only audit logs record everything for forensic replay.

Agent SRE provides reliability engineering. SLO enforcement, error budgets, circuit breakers are available to prevent cascading failures, replay debugging and chaos engineering. The production observability patterns you'd expect from a team that runs Azure at scale.

All four components work together to answer a fundamental question: is this agent allowed to do what it's trying to do, and is it doing it safely?

This is genuinely hard infrastructure to build correctly. Identity, policy enforcement, execution isolation, and reliability engineering each have deep rabbit holes, and Microsoft has the engineering depth to go down all of them properly.

Where Flow Adds a Complementary Layer

The toolkit governs agent behavior — permissions, identity, execution boundaries, reliability. Flow governs agent output i.e. the actual data the agent produces when it completes an action.

These are different concerns. The toolkit ensures the agent is authorized and operating safely. Flow ensures the data the agent produces is correct and hasn't been tampered with before reaching the downstream system.

One reasonable question to ask would be: couldn't AgentMesh's trust gates or the Agent OS policy engine handle data validation too? Technically, you could write OPA/Rego policies that inspect payload fields — Rego is expressive enough to check input.payload.amount > 0. But policy engines are designed to return allow/deny decisions, not structured validation errors with field-level messages that an agent can use to self-correct and resubmit. You'd also be mixing authorization concerns with domain-specific business logic in the same policy files. Also, you wouldn't get HMAC-based payload verification or human approval routing. It's a bit like using a firewall for input validation — it can inspect packet contents, but that doesn't make it the right layer for checking whether an invoice total matches its line items.

Think about the OWASP compliance mapping in the toolkit. ASI-05 addresses unexpected code execution through privilege rings and sandboxing. This makes sure that the agent can't run arbitrary code. That's the right control for that risk. But once the agent produces a result through an approved tool call — an invoice, a purchase order, a compliance report — there's a different question to answer: is the data in that result actually correct?

An agent can be fully authorized, properly authenticated, running within its privilege ring, with no circuit breaker tripped. The policy engine approved the action. And the agent still submits "currency": "usd" instead of "USD", calculates a total that's off by a rounding error, or drops a required field. These are domain-specific data quality issues that a behavioral governance layer isn't designed to catch, and honestly shouldn't try to, that would mix concerns and bloat the policy engine with domain logic.

This is what Flow was built for. You define a gate with a schema and business rules specific to your domain, and the agent's output gets validated before it reaches the downstream system. Validation Failures return structured errors which the agent can use to self-correct. Passed validations return a validation_id — an HMAC-SHA256 hash of the validated payload which the downstream system can independently verify.

How the Two Layers Work Together

The distinction maps to how we think about security in traditional systems. Authentication and authorization tell you who's making a request and whether they're allowed to. Input validation tells you whether the data they're sending is well-formed and correct. You've always needed both. The agentic world isn't different.

The toolkit handles the rows above the line. Flow handles the rows below it. Together, they cover the pipeline end to end.

A Practical Example

Say you have an order processing agent running in an environment with the toolkit deployed. The policy engine confirms the agent has permission to submit orders. AgentMesh verified its identity. The runtime supervisor confirmed it's operating within its privilege ring.

The agent submits this order:

{
  "order_id": "ORD-2847",
  "vendor": "Acme Corp",
  "amount": -500,
  "currency": "usd",
  "line_items": []
}

From the toolkit's perspective, everything checks out. The agent was authorized, authenticated, and operating within bounds. The policy engine approved the action. And it should approve it — the toolkit's job is to enforce behavioral governance, not validate business data.

Flow picks up where the toolkit leaves off. A gate with the appropriate schema and rules catches three issues:

{
  "success": false,
  "errors": [
    { "field": "amount", "message": "Must be >= 0" },
    { "field": "currency", "message": "Must be one of: USD, EUR, GBP" },
    { "rule": "line_items.length > 0", "message": "Must have at least one line item" }
  ]
}

The agent self-corrects using the structured feedback, resubmits, and gets a validation_id on success. The downstream system verifies the ID before accepting the data. The toolkit made sure the right agent submitted the order safely. Flow made sure the order itself was correct.

Performance — Both Layers Are Essentially Free

One thing the toolkit's benchmarks highlight is that governance overhead should be invisible relative to LLM latency. Their policy evaluation adds 0.01–0.1ms. An LLM API call takes 200–3,000ms. I think they're exactly right about this — governance shouldn't be the bottleneck, and at those numbers it never will be.

Flow operates at a different timescale because it's doing more work per evaluation — parsing payloads, validating schemas against variable arrays, running expression-based business rules through a recursive descent parser. Our benchmarks show ~50ms server-side validation for enterprise-scale payloads (21 schema variables, 10 business rules, 900 line items in a single payload). For typical payloads (a few KB), it's single-digit milliseconds.

Combined, both layers add maybe 50–60ms to a pipeline where the LLM inference took 500–3,000ms. You're paying a negligible cost for behavioral governance and output validation together.

The Bigger Picture

Between the OWASP Agentic Top 10, the AWS Agentic AI Security Scoping Matrix, Snapchat's Auton framework, and now Microsoft's toolkit, the industry is converging on something I think is important: agent governance is not a single problem with a single solution. It's a stack of specialized layers, each addressing different risks at different points in the pipeline.

Microsoft releasing this toolkit validates the category in a way that benefits everyone building in the space. When the company that runs Azure tells the world "agent governance is infrastructure, here's our reference implementation for free," it moves the conversation from "do we need agent governance?" to "which layers do we still need to add?"

We think output validation is one of those layers. Not because the toolkit missed something, but because domain-specific data correctness is a separate concern that deserves its own specialized tooling. Checking whether an invoice has the right currency code, whether an order total matches its line items, or whether a compliance report includes all required fields isn't a policy evaluation problem. It's a schema and business rule problem with optional human review in the loop.

That's what we built Flow to handle. If you're deploying the Agent Governance Toolkit and want to add output validation to the pipeline, try dropping a Flow gate between the governed agent and your downstream system. The free tier gives you 500 validation runs per month and three gates — enough to see how the two layers work together in practice.

Rynko Flow is a validation gateway for AI agent outputs. Try it free or read the docs.

IBM closed its $11 billion acquisition of Confluent, the Kafka-based streaming platform used by 40% of Fortune 500 companies. The thesis is sound: enterprises moving from AI experimentation to production need live, continuously flowing data — not batch exports that arrive hours late. As Rob Thomas (IBM SVP) put it, "AI decisions need to happen just as fast" as the transactions generating the data. That's exactly right, and Confluent is the best platform in the world for making it happen.

Meanwhile, AWS announced a collaboration with Cerebras to bring wafer-scale inference to Amazon Bedrock. The CS-3 delivers thousands of times more memory bandwidth than the fastest GPU, targeting the decode bottleneck that slows agentic workloads. Andrew Feldman (Cerebras CEO) called it "blisteringly fast inference." Their disaggregated architecture pairs Trainium for compute-heavy prefill with Cerebras WSE for bandwidth-heavy token generation — an order of magnitude faster inference than what's available today. For anyone building real-time agentic workflows, this is a big deal.

These are the kind of infrastructure investments that make agentic systems practical at enterprise scale. They also got me thinking about where Rynko Flow fits into this picture.

The Pipeline and Where Each Layer Contributes

The enterprise AI pipeline looks roughly like this:

IBM + Confluent handle the input: getting live, governed, trustworthy data to the agent. AWS + Cerebras handle the processing: making the agent produce output fast enough for real-time operations. Both are necessary — an agent making decisions on stale data is worse than no agent at all, and an agent that takes 30 seconds to respond isn't useful for time-sensitive workflows.

What we've been focused on at Rynko is the next step in that pipeline: once the agent processes that real-time data at speed and produces a result — an invoice, a purchase order, a compliance report — how do you validate that the result is correct before it reaches the downstream system?

This is a genuinely different problem from data freshness or inference speed, and it's the problem we built Flow to solve. Even with perfect input data, agents can submit "usd" instead of "USD", produce a total that's off by a rounding error, or silently drop a required field. The data flowing in was pristine. The processing was fast. The output still needs a checkpoint.

What Flow Adds to the Pipeline

Flow is a validation gateway that sits between the agent's output and your downstream systems. You define a gate with a schema and business rules, the agent submits its output, and Flow validates it before the data moves forward. Failed submissions return structured errors the agent can use to self-correct. Passed submissions return a tamper-proof validation_id that the downstream system can verify to confirm nothing was modified in transit.

Say you have an order processing agent. Confluent is streaming real-time order events from your POS systems, inventory databases, and payment providers. The agent processes these events and produces a purchase order to send downstream. Here's the Flow gate that checks the agent's output:

Schema:
  - order_id: string, required
  - vendor: string, required
  - amount: number, required, min 10
  - currency: string, required, enum [USD, EUR, GBP]
  - line_items: array of objects, required

Business Rules:
  - amount > 0 ("Order amount must be positive")
  - amount <= 100000 ("Single order cannot exceed $100,000")
  - line_items.length > 0 ("Must have at least one line item")

The agent submits its payload. Flow validates it against the schema and evaluates every business rule. If the agent submitted amount: -500, it gets back:

{
  "success": false,
  "status": "validation_failed",
  "errors": [
    { "rule": "amount > 0", "message": "Order amount must be positive" }
  ]
}

The agent self-corrects and resubmits. When validation passes, the response includes a validation_id:

{
  "success": true,
  "status": "validated",
  "validation_id": "val_4f546e9bcb76f120c4984d72"
}

That validation_id is an HMAC-SHA256 hash of the validated payload, computed using canonical JSON serialization with recursively sorted keys. This means even if the payload passes through multiple systems that reorder the JSON keys or reformat the whitespace, the verification still works. The downstream system receives the payload and the validation_id from the agent, then calls Flow to verify:

curl -X POST https://api.rynko.dev/api/flow/verify \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "validation_id": "val_4f546e9bcb76f120c4984d72",
    "payload": { "order_id": "ORD-001", "vendor": "Acme", "amount": 500, ... }
  }'

{
  "verified": true,
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "gateName": "Order Validation",
  "gateSlug": "order-validation"
}

If the agent tampered with the payload after validation — changed the amount, added a field, removed a required value — verification returns verified: false. The downstream system knows not to trust the data.

Validation Doesn't Have to Be a Bottleneck

One concern I hear is whether validation adds meaningful latency to a real-time pipeline. We benchmarked Flow against enterprise-scale payloads — the kind of data you'd see flowing through Kafka in a large manufacturing or logistics operation.

We tested with a Sterling Commerce OMS-style order payload: 21 schema variables, 10 business rules, 900 order line items. The payloads were around 9MB for XML and 7.3MB for JSON.

The validation itself — schema checks plus 10 business rule evaluations — takes about 50 milliseconds. The rest is network transfer. At typical payload sizes (a few KB for a single order or invoice), the validation adds single-digit milliseconds. For a 30-line order at 0.3MB, the total round-trip was 1,960ms with most of that being upload time over a standard connection.

Server-side processing is fast because Flow runs validation in-memory: schema validation against a pre-compiled variable array, then expression evaluation through a recursive descent parser for each business rule. No database queries during validation. Persistence runs asynchronously after the response is sent — payloads go to S3, run metadata goes to Postgres, both fire-and-forget so the agent gets its response immediately.

For Kafka-speed pipelines where even 50ms matters, Flow also supports webhook delivery — validation happens, and the validated payload is pushed directly to your endpoint without the agent needing to relay it. That eliminates the agent-as-middleman entirely.

All Three Layers Together

Here's how I'd architect an agentic pipeline with all three layers working together:

Confluent handles data-in-motion: live events, governed, streaming at scale. Cerebras on Bedrock processes those events fast — the disaggregated Trainium+WSE architecture means agents produce structured output at speeds that make real-time workflows practical. Flow validates that output against your schema and business rules, returns errors for self-correction or a tamper-proof validation_id on success. The downstream system verifies the validation_id before accepting the data.

Three separate problems, three separate layers. Each one does its part well. Confluent ensures the agent gets good data. Cerebras ensures the agent processes it fast. Flow ensures the output is correct before it reaches production systems.

Why This Matters Now

I want to be clear: Flow doesn't replace anything IBM, Confluent, AWS, or Cerebras are building. They're solving data infrastructure and inference speed — foundational problems that every enterprise needs addressed. These are massive, hard engineering challenges, and both acquisitions and partnerships reflect the kind of investment this space deserves.

What Flow adds is a complementary output validation layer. As agents move from experimental to production, and as the data flowing through them gets faster and the inference gets cheaper, the volume of agent-generated outputs hitting downstream systems is going to increase significantly. Having a validation checkpoint in that pipeline — one that catches domain-specific errors, enforces business rules, and provides tamper-proof verification — becomes more valuable as the rest of the stack gets faster.

AWS's Agentic AI Security Scoping Matrix (published November 2025) calls out many of the capabilities Flow provides: approval gateway enforcement, agent controls, audit trails, agency perimeters. We've mapped Flow against every scope in that framework — it covers Scopes 2 and 3 well, with partial coverage at Scope 4 where fully autonomous agents need capabilities beyond what a validation gateway provides alone.

If you're building agentic workflows on Kafka, Bedrock, or both, try dropping a Flow gate between your agent and your downstream system. The free tier gives you 500 validation runs per month and three gates — enough to see how output validation fits into your pipeline.

Rynko Flow is a validation gateway for AI agent outputs. Try it free or read the docs.

The key insight: When agents fail and retry without clear guidance, it's not a minor inconvenience — it's a reliability failure. Every failed correction loop is a moment where your automation is stuck in a cycle of non-compliance. Gate Intelligence identifies the friction points that prevent agents from reaching a successful state, and feeds that knowledge back into the gate's contract so the next agent gets it right on the first try.

When we launched Flow, the pitch was straightforward: define a gate with a schema and business rules, point your agent at it, and Flow validates the payload before it reaches your database. Schema checks, expression-based rules, optional human approval. It works well — agents submit data, gates validate it, failed submissions come back with structured errors the agent can act on.

But we were sitting on a pile of useful data and not doing anything with it.

Every run Flow processes is stored: the input payload, the validation verdict, which rules passed, which failed, and the exact values that caused the failure. For agents that self-correct, we track the full chain — first attempt, second attempt, third, until either the agent gets it right or gives up. That's tens of thousands of data points per gate per week, and until now, it only showed up as numbers on the analytics dashboard.

Gate Intelligence turns that data into concrete suggestions for improving your gates.

The Problem It Solves

Here's a real pattern we saw in our own test gates. We set up an invoice validation gate with five business rules: amount must be positive, currency must be a 3-letter uppercase code, vendor can't be empty, line items must sum to the total, and there must be at least one line item. Standard stuff.

When we ran agents against it, 40% of first attempts failed the currency format rule. The agents were submitting "usd" and "eur" instead of "USD" and "EUR". Another 25% failed the line items sum check — off by a fraction of a cent due to floating-point rounding. 15% of submissions omitted the vendor field entirely.

None of these are schema problems. The schema says currency is a string, vendor is required, amount is a number. All correct. The issue is that the gate's documentation and rules don't give agents enough context to get it right on the first try. The currency rule says "must equal its own uppercase version" — technically precise, but a Claude or GPT model reading the MCP tool description doesn't know that means "must be uppercase ISO 4217."

When agents fail and retry without that context, the automation isn't saving time — it's stuck. Each failed loop is a moment where your pipeline is spinning instead of producing results. If an agent needs five attempts and 45 seconds to pass a rule that a single well-placed hint would have fixed on the first try, the gate itself is the bottleneck.

Gate Intelligence identifies these patterns automatically and tells you what to do about them.

What It Computes

Every hour, a background job runs for each active gate. It analyzes the last 7 days of runs and computes six metrics:

Per-rule failure rates — what percentage of first-attempt submissions fail each rule, with trend direction compared to the previous 7-day window. If your "amount must be positive" rule went from 5% failure to 15%, that's flagged as trending up.

Common failure values — the actual values agents submitted that caused failures. For the currency rule, this surfaces "usd", "eur", "gbp" as the top offenders. For a numeric rule, it might show 0, -1, or 99999.999. These values are what make suggestions actionable — instead of "rule X fails a lot," the system can say "agents are submitting lowercase currency codes."

Field omission rates — how often required schema fields are missing from submissions. A 30% omission rate on the vendor field means agents don't realize it's required, or the field name isn't clear enough.

Chain convergence — of all the failed submissions that triggered a correction chain, what percentage eventually succeeded? If agents submit, fail, retry, fail again, and give up 70% of the time, that's a fundamental reliability problem. A 33% convergence rate doesn't just mean "some retries" — it means your automation succeeds less than a third of the time. For any system that's supposed to run autonomously, that's a non-starter.

Average chain length and time-to-correction — how many attempts does it take, and how long does the cycle last? Two attempts averaging 3 seconds is healthy. Five attempts averaging 45 seconds means the agent is struggling.

Pattern Detection

Raw metrics tell you what is failing. Pattern detection tells you why.

The system examines common failure values and classifies them into four fixable patterns:

• Case mismatch — the submitted value is a lowercase version of what's expected. "usd" vs "USD", "active" vs "Active". This usually means the gate needs to either make the rule case-insensitive or add explicit guidance about expected casing.

• Rounding tolerance — a numeric value is within 1% of the expected threshold but fails because of floating-point precision. An amount of 99.999 failing an exact equality check where the expected sum is 100.00. The fix is usually adding a small tolerance to the rule.

• Type coercion — a string representation of a number where a number is expected. The string "42" instead of the number 42. Common with agents that serialize JSON from natural language.

• Empty string — an empty string where a non-empty value is expected. Distinct from a missing field — the agent knows the field exists but doesn't have a value for it.

These patterns feed into the suggestions. Instead of a generic "rule X fails 60% of the time," the suggestion says "the currency format rule fails 60% of the time — agents submit lowercase currency codes (usd, eur, gbp). Consider adding a note that currency must be uppercase ISO 4217."

Suggestions and the Intelligence Tab

Each gate now has an Intelligence tab alongside Configuration and Performance. The tab shows a summary bar with insight counts by severity, per-rule failure rates with trend arrows, field omission rates, chain convergence metrics, and a health trend chart built from historical snapshots.

Below the analysis cards, concrete suggestions appear as dismissable cards with three severity levels:

Each suggestion has three actions: Apply, Dismiss, and Snooze (hide for 7 days).

Version-Controlled Hints

This is where the architecture gets interesting. The first version of "Apply" directly modified the gate's description field — injecting hint text like "Common mistakes: agents submit lowercase currency codes." It worked, but it was a bad design for three reasons.

First, no version control. The description change bypassed the gate's draft/publish pipeline. In regulated environments — banking, healthcare, insurance — operators need to know exactly when and why a gate's contract changed. A direct write to the description is invisible in the version history.

Second, no audit trail. If an agent's behavior shifts after someone clicks "Apply" (for better or worse), there's no correlation between the click and the behavior change.

Third, no review step. The hint goes live immediately. If Gate Intelligence generates five suggestions and the operator clicks Apply on all of them, five changes hit production with no review.

So we changed the approach. Hints are now a first-class versioned field on the gate — stored alongside the schema, business rules, and identity key fields. When you click "Apply" on a suggestion, it adds the hint text to the gate's draft version. If no draft exists, it creates one. The hint doesn't go live until you review it in the gate configurator and publish.

The gate configurator now has a dedicated "Hints" panel sitting between the Details and Schema steps — visible at a glance without opening any dialog. You can see what Intelligence suggested, edit the text, add your own custom hints, or remove ones you don't want. When you're satisfied, you publish the gate version — which goes through the existing audit log, resets circuit breakers, and notifies connected MCP sessions that the tool description has changed.

This means hints get the same treatment as any other gate configuration change: versioned, auditable, rollbackable.

How Hints Reach the Agent

The MCP tool description for each gate is assembled from three sources:

Submit data to Invoice Validation
Validates invoice payloads before processing to the ERP system.

Business rules:
- amount_positive: Amount must be greater than zero
- currency_format: Currency must be valid ISO 4217
- line_items_match: Line item totals must equal invoice amount

--- Best Practices ---
- Currency must be uppercase ISO 4217 (e.g., USD, EUR, not usd)
- Line item totals must sum to the invoice amount within ±0.01
- Vendor name is required — do not submit an empty string

The gate description is always included. Business rules are always appended so the agent knows the constraints. The "Best Practices" section only appears when the auto-hints toggle is enabled on the gate — it's off by default because it changes what agents see, and the gate owner should make that decision deliberately.

The key improvement from the original architecture: reading hints is now a simple array read from the published gate record, not a database query against the insights table. The old approach queried the insights service every time an MCP tool description was built, which meant a database hit on every tool list request. The new approach reads directly from the gate record — the hints were copied there at publish time. This matters because MCP tool descriptions are assembled on every session connection and tool refresh. Moving from a database lookup to a direct read keeps the tool-build path fast and predictable, which is critical when you're serving multiple concurrent agent sessions.

Historical Snapshots and Trend Analysis

Each time the intelligence job runs, it saves a snapshot with aggregate metrics: total runs, overall failure rate, per-rule failure rates, field omission rates, chain convergence, and suggestion counts. This creates a time series of gate health that's visible in the Intelligence tab as a bar chart.

The chart color-codes each bar: red for failure rates above 50%, amber for 20–50%, and the primary color below 20%. Hovering shows the exact values and date. Over time, you can see whether applying suggestions actually improved the gate's success rate — which is the whole point.

What's Next

Gate Intelligence today is reactive — it analyzes historical data and suggests improvements. There are two directions on the roadmap:

Proactive schema evolution: if Intelligence detects that agents consistently submit a field that isn't in the schema (say, a tax rate keeps appearing in payloads that only define amount and currency), it suggests adding it. This requires analyzing raw payloads beyond just validation results, which is a different data pipeline.

AI Judge integration: the current business rules are deterministic expressions. We're building an "AI Judge" mode that evaluates payloads using an LLM for semantic checks that can't be expressed as expressions — things like "the description should be professional in tone" or "the address looks like a real postal address." Intelligence would track AI Judge pass/fail rates the same way it tracks expression rules, but the suggestion engine would need to account for the non-deterministic nature of LLM evaluation.

Neither is shipped yet, but the foundation is designed for them. The analysis pipeline, suggestion engine, versioned hints, and snapshot time series are all extensible — adding a new data source feeds into the same pattern detection and suggestion framework without rearchitecting anything.

Getting Started

If you have an active Flow gate with at least 50 runs, Intelligence will start generating insights on the next hourly cycle. Open any gate, click the Intelligence tab, and hit Refresh to trigger analysis immediately.

We're rolling it out gradually — it's available today for all paid tiers (Starter, Growth, Scale) and will be available on the Free tier once we're confident in the compute overhead.

Whether your agents are running on AWS Bedrock, OpenAI's API, or any other provider — the validation layer is where reliability is won or lost. If your gates are rejecting 60% of first attempts and your correction chains converge less than half the time, your automation isn't autonomous. It's just expensive retry logic. Gate Intelligence gives you the data to fix that, and the versioned hints to make the fix stick.

Flow docs: docs.rynko.dev/flow

Get started: app.rynko.dev/signup — free tier, 500 runs/month, 3 gates, no credit card.

I read through it and realized we'd already implemented a significant portion of what it recommends, particularly at Scopes 2 through 4. But I also found gaps worth being honest about. This post walks through each scope, maps it to Flow's current capabilities, and flags where we're still building.

A Quick Primer on What Flow Does

For context if you haven't seen Flow before: Rynko Flow is a validation gateway that sits between AI agents and downstream systems. You define a gate with a JSON schema and business rules, your agent submits payloads to it, and Flow validates the data before it proceeds. Failed validations return structured errors the agent can use to self-correct. Successful validations return a tamper-proof validation_id. Optionally, you can add human approval steps and webhook delivery.

The pipeline:

Gates are exposed as MCP tools, so agents discover and use them without per-gate integration code. We also support REST API submission for non-MCP agents.

One distinction that matters throughout this post: Flow is a validation checkpoint, not a centralized orchestrator. It doesn't manage agent workflows or decide what runs next. The agent (or whatever framework orchestrates it — LangGraph, CrewAI, your own code) decides when to call a gate and what to do with the result. Flow's job is narrower: validate the data, return a verdict, and track what happened.

That said, Flow's webhook delivery does enable a form of event-driven orchestration — when a payload passes validation, the webhook can trigger the next agent or service in a pipeline, creating loosely-coupled handoffs without a central coordinator. This means Flow covers some of the AWS framework's security dimensions deeply (audit, agent controls, agency perimeters) and has a partial but real story for orchestration through webhooks.

With that context, here's how Flow maps to each scope in the AWS framework.

Scope 1: No Agency

What AWS describes: Systems with human-initiated processes and no autonomous change capabilities. The agent follows predefined paths, processes data within workflow nodes, but can't modify anything. Read-only operations. Fixed execution paths.

Security focus: Process integrity, boundary enforcement, preventing agents from exceeding their boundaries.

How Flow maps here: Flow isn't really designed for Scope 1. If your agent is purely read-only and follows a fixed workflow with no ability to produce output that reaches external systems, you don't need a validation gateway — there's nothing to validate.

That said, Flow's schema validation does share DNA with one of Scope 1's key requirements: "input validation at each workflow step boundary." If you're building a pipeline where each stage processes data and hands it to the next, you could place a Flow gate between stages to validate that each node's output conforms to the expected shape. But that's using Flow as plumbing, not as an agent governance layer.

Flow coverage: Minimal — and that's fine. Scope 1 agents don't produce autonomous outputs.

Scope 2: Prescribed Agency

What AWS describes: Human-initiated, human-approved agentic actions. Agents can gather information, analyze data, and prepare recommendations, but all actions of consequence require explicit human approval. This is the "human in the loop" (HITL) scope.

Key characteristics:

• Agents can execute change with human review and approval

• Real-time human oversight with approval workflows

• Bidirectional interaction — agents can ask humans for context

• Audit trails of all human approval decisions

Security focus: Securing approval workflows, preventing agents from bypassing human authorization, and maintaining oversight effectiveness.

How Flow maps here: This is where Flow starts to fit well. The approval workflow was one of the first features we built into Flow, and it maps directly to what the AWS framework calls "approval gateway enforcement."

Here's how each Scope 2 security dimension looks in Flow:

The Scope 2 implementation consideration that stood out to me was "time-bounded approval tokens with automatic expiration." We built this: magic links for external reviewers are HMAC-SHA256 signed, expire in 72 hours, and are single-use for approval actions. The reviewer doesn't need a Rynko account — they click the link, see the payload rendered with safe content (sanitized HTML/Markdown), and approve or reject.

One gap: the paper mentions "cryptographically signed approval decisions." Our approval decisions are stored in the database with reviewer identity and timestamp, but we don't produce a standalone cryptographic proof of the decision. It's an area where we could do more.

Flow coverage: Strong. Approval workflows, audit trails, scoped identity, and time-bounded reviewer access align closely with Scope 2 requirements.

Scope 3: Supervised Agency

What AWS describes: Human-initiated, but the agent executes autonomously. The agent makes decisions and takes actions without further approval. Humans define objectives and trigger execution, but agents operate independently through dynamic planning and tool usage. Optional human intervention points exist, but the agent can proceed without them.

Key characteristics:

• Agents can execute change with no (or optional) human review

• Dynamic planning and decision-making during execution

• Direct access to external APIs and systems

• Persistent memory across extended sessions

• Autonomous tool selection and orchestration within defined boundaries

Security focus: Maintaining control during autonomous execution, scope management, and behavioral monitoring.

How Flow maps here: This is Flow's primary operating mode. Most teams using Flow today have agents that submit data autonomously — no human in the loop — and rely entirely on the gate's schema and business rules to catch problems. The agent self-corrects from structured errors, and Flow's circuit breaker intervenes if the agent enters a failure loop.

The self-correction chain tracking deserves specific mention here. The AWS paper talks about "reasoning chain capture" — being able to see why an agent made the decisions it did. Flow's chain tracking gives you a concrete version of this for validation: when an agent submits to a gate, fails, reads the errors, and resubmits, the entire sequence is linked by a correlationId. You can see exactly what the agent submitted each time, which rules it violated, what it fixed, and whether it eventually succeeded. In the webapp, chains are displayed as collapsible groups — the latest attempt shows as the primary row with a badge showing "3 attempts," and expanding reveals the full correction timeline.

The circuit breaker is Flow's implementation of the "automated safety checks" requirement. When an agent keeps failing the same gate — tracked per session for MCP agents, per payload hash for REST agents — the circuit breaker trips after a configurable number of consecutive failures. The gate transitions to a paused state, the system sends in-app and email notifications to the gate creator, and all further submissions are blocked until the cooldown expires or a new gate version is published.

Here's what makes the circuit breaker interesting from the AWS framework perspective: it's an example of graceful degradation, which the paper calls out as a key architectural pattern. The paper says: "Design systems to automatically reduce autonomy levels when security events are detected." The circuit breaker does exactly this — when the agent can't produce valid output, Flow reduces the agent's effective autonomy by blocking further submissions and notifying the human operator.

Flow coverage: Strong to comprehensive. Self-correction chains, circuit breaker, runtime validation, MCP session tracking, and structured audit trails address most Scope 3 requirements.

Scope 4: Full Agency

What AWS describes: Fully autonomous AI that initiates its own activities based on environmental monitoring, learned patterns, or predefined conditions. No human triggers the agent — it operates continuously, makes independent decisions about when and how to act. The highest level of agency and risk.

Key characteristics:

• Self-directed activity initiation based on environmental triggers

• Continuous operation with minimal human oversight

• High to full degrees of autonomy in goal setting, planning, and execution

• Dynamic interaction with multiple external systems and agents

• Capability for recursive self-improvement

Security focus: Continuous behavioral validation, enforcing agency boundaries, preventing capability drift, and maintaining organizational alignment.

How Flow maps here: Flow isn't a Scope 4 system itself — it doesn't initiate actions or make autonomous decisions. But it serves as a governance layer that Scope 4 agents submit to. The distinction matters: Flow doesn't control what the agent does; it controls what outputs the agent can successfully land in downstream systems. In the AWS framework's terms, Flow provides the "Advanced Deterministic Guardrails" that Scope 4 requires.

I want to be transparent about where the gaps are, because the Scope 4 requirements are genuinely hard. The paper calls for "continuous monitoring with machine learning-based anomaly detection" and "automated response systems for behavioral deviations." Flow's circuit breaker is an automated response system, but it's simple — it counts consecutive failures. It doesn't analyze payload content for anomalies, detect drift in agent behavior patterns over time, or predict when an agent is likely to start producing invalid output.

That said, Flow provides the infrastructure that makes Scope 4 deployment safer:

1. Every submission is validated — the agent can't skip the gate. Schema + business rules are deterministic, not probabilistic. A Scope 4 agent that submits an order with a negative total gets rejected regardless of how autonomously it's operating.

2. Self-correction is tracked — you can see whether a Scope 4 agent is self-correcting successfully (resilient autonomy) or spiraling into repeated failures (failing autonomy). Chain tracking gives you this visibility without instrumenting the agent itself.

3. Automated containment — the circuit breaker pauses the gate when failures accumulate. This is the "failsafe mechanism that can halt operations when confidence drops" that the paper recommends for Scope 4.

4. Human re-entry point — when the circuit breaker trips, the gate creator gets notified (in-app + email). This is the "human ability to inject strategic guidance without disrupting operations" pattern. The human publishes a new gate version (potentially with adjusted rules), which reactivates the gate and resets circuit breakers.

Flow coverage: Partial but meaningful. Flow provides the deterministic guardrails, automated containment, and audit infrastructure that Scope 4 requires. The gaps are in ML-based anomaly detection, agent identity attestation, and cross-session learning — areas that require capabilities beyond what a validation gateway provides on its own.

The Six Security Dimensions — Summary Matrix

Here's a consolidated view of how Flow maps across all four scopes and six dimensions:

The Key Architectural Patterns

The AWS paper concludes with five architectural patterns for agentic AI deployments. Flow aligns with four of them:

Progressive autonomy deployment — "Start with Scope 1 or 2 implementations and gradually advance." Flow supports this directly. A gate can start with approval workflows (Scope 2 — human reviews every submission). Once you're confident in the schema and rules, remove the approval step and let the agent operate autonomously (Scope 3). The gate's validation logic stays the same; you're just adjusting the human oversight level.

Continuous validation loops — "Establish automated systems that continuously verify agent behavior against expected patterns." This is literally what Flow does. Every agent submission is validated against the gate's schema and business rules. The self-correction loop (submit → fail → read errors → fix → resubmit) is a continuous validation loop operating at the individual submission level.

Human oversight integration — "Maintain meaningful human oversight through strategic checkpoints, behavioral reporting, and manual override capabilities." Flow's approval workflows are the strategic checkpoints. Chain tracking and circuit breaker notifications are the behavioral reporting. Gate versioning and manual pause/resume are the manual override capabilities.

Graceful degradation — "Design systems to automatically reduce autonomy levels when security events are detected." The circuit breaker does this: when an agent accumulates consecutive failures, the gate pauses, notifications fire, and the agent's effective autonomy drops to zero until a human intervenes or the cooldown expires. The paper specifically recommends systems that "automatically inject tighter restrictions such as requiring more HITL or reducing the actions an agent can take" — this is exactly what happens when a gate transitions from auto-approve to paused.

The one pattern we don't cover well is layered security architecture — "defense in depth with security controls at multiple levels." Flow operates at the application layer (validating agent outputs). It doesn't provide network-level controls, model-level guardrails, or infrastructure-level isolation. Teams building Scope 3-4 systems need Flow as one layer in a broader security stack, not as the only layer.

What We're Building Next

Reading the AWS framework confirmed some things on our roadmap and added others:

AI Judge (semantic validation) — Currently, Flow's validation is deterministic: JSON Schema types and expression-based business rules. For Scope 4 agents producing unstructured or semi-structured outputs, deterministic rules aren't always enough. We're building an LLM-based evaluation mode where a second model reviews the agent's output against criteria defined in natural language. This addresses the "continuous behavioral validation" gap at Scope 4.

Approval timeout enforcement — Our approval workflow creates a pending_approval state, but there's no automatic expiration. The paper's Scope 2 recommendation of "time-bounded approval tokens with automatic expiration" applies here. We're adding configurable timeout with auto-reject or auto-escalate behavior.

Agent behavioral baselining — The paper's Scope 4 requirements for "pattern analysis" and "predictive monitoring" are beyond what a simple failure counter provides. We're exploring tracking submission patterns per agent (payload shape, submission frequency, validation pass rate) and flagging deviations. Not ML-based yet, but statistical baselines that surface when an agent's behavior changes.

Where Flow Fits in Your Agentic Architecture

Rynko Flow isn't a complete Scope 4 security stack — no single product is. But it provides the validation gateway, automated containment, and audit infrastructure that the AWS framework identifies as critical across Scopes 2-4.

If you're building agents that produce data destined for production systems — orders, invoices, tickets, customer records — Flow gives you deterministic guardrails that work regardless of which model or framework your agent uses. The gate doesn't care whether the agent is a Claude tool-use loop, a LangGraph pipeline, or a custom orchestrator. It validates the output, tracks the correction chain, and trips the circuit breaker if things go sideways.

The AWS framework is worth reading in full — it provides a structured way to think about where your agent sits on the agency/autonomy spectrum and what security controls you need at that level. And if you're at Scope 2 or above, a validation gateway isn't optional — it's one of the six critical security dimensions.

Paper: The Agentic AI Security Scoping Matrix

Flow docs: docs.rynko.dev/flow

Get started: app.rynko.dev/signup — free tier, 500 runs/month, 3 gates, no credit card.

I ran into this when building an order processing pipeline with LangGraph. The extraction node would occasionally produce negative amounts, invalid currencies, or missing fields. The downstream nodes — pricing, invoicing, fulfillment — would silently process the bad data. By the time someone noticed, the damage was already in the database.

The typical fix is writing validation logic inside each node. That works, but it means every node carries its own schema checks, the validation rules are scattered across your codebase, and there's no central place to see what's failing and why.

So I hooked up Rynko Flow as an external validation step in the graph. The agent extracts data, Flow validates it against a schema and business rules, and only if it passes does the pipeline continue. If it fails, the agent gets structured errors it can use to self-correct.

What You'll Build

A LangGraph agent with three nodes:

1. Extract — LLM extracts order data from a natural language request

2. Validate — Submits the extracted data to a Rynko Flow gate

3. Process — Handles the validated order (or routes back for correction)

The graph looks like this:

extract → validate → process
              ↓ (if failed)
          extract (retry with error context)

Prerequisites

pip install langgraph langchain-openai httpx

You'll also need:

• A Rynko account (free tier works)

• A Flow gate configured with your order schema

• An OpenAI API key (or any LangChain-compatible LLM)

Setting Up the Flow Gate

Create a gate in the Flow dashboard with this schema:

Add a business rule: amount >= 10 with error message "Order amount must be at least $10."

If you already have a Pydantic model, you can import the schema directly — run YourModel.model_json_schema() and paste the output into the gate's Import Schema dialog. There's a tutorial for that.

Save and publish the gate. Note the gate ID — you'll need it in the code.

The Validation Client

First, a small wrapper around the Flow API. This is what the validate node will call:

import httpx
import os

RYNKO_BASE_URL = os.environ.get("RYNKO_BASE_URL", "https://api.rynko.dev/api")
RYNKO_API_KEY = os.environ["RYNKO_API_KEY"]

def validate_with_flow(gate_id: str, payload: dict) -> dict:
    """Submit a payload to a Flow gate and return the result."""
    response = httpx.post(
        f"{RYNKO_BASE_URL}/flow/gates/{gate_id}/runs",
        json={"payload": payload},
        headers={
            "Authorization": f"Bearer {RYNKO_API_KEY}",
            "Content-Type": "application/json",
        },
        timeout=30,
    )
    return response.json()

This returns the full validation result — status, errors, validation ID, the works. The important fields are status (either "validated" or "validation_failed") and errors (an array of specific field-level issues when validation fails).

Defining the Graph State

LangGraph uses a typed state that flows between nodes. Ours tracks the user request, extracted data, validation result, and retry count:

from typing import TypedDict, Optional

class OrderState(TypedDict):
    user_request: str
    extracted_data: Optional[dict]
    validation_result: Optional[dict]
    validation_errors: Optional[str]
    retry_count: int
    final_result: Optional[str]

The Three Nodes

Extract Node

The LLM extracts structured order data from the user's natural language request. If there were previous validation errors, they're included in the prompt so the LLM can correct its output:

from langchain_openai import ChatOpenAI
import json

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

GATE_ID = os.environ["FLOW_GATE_ID"]  # Your gate ID

def extract_order(state: OrderState) -> dict:
    error_context = ""
    if state.get("validation_errors"):
        error_context = (
            f"\n\nYour previous extraction had validation errors:\n"
            f"{state['validation_errors']}\n"
            f"Fix these issues in your new extraction."
        )

    response = llm.invoke(
        f"Extract order data from this request as JSON with fields: "
        f"vendor (string), amount (number), currency (string, one of USD/EUR/GBP/INR), "
        f"po_number (string, optional).\n\n"
        f"Request: {state['user_request']}"
        f"{error_context}\n\n"
        f"Respond with ONLY valid JSON, no markdown."
    )

    try:
        extracted = json.loads(response.content)
    except json.JSONDecodeError:
        extracted = {"vendor": "", "amount": 0, "currency": ""}

    return {"extracted_data": extracted}

Validate Node

This is the Flow integration — submit the extracted data to the gate and capture the result:

def validate_order(state: OrderState) -> dict:
    result = validate_with_flow(GATE_ID, state["extracted_data"])

    if result.get("status") == "validation_failed":
        errors = result.get("error", {}).get("details", [])
        error_text = "\n".join(
            f"- {e.get('field', e.get('rule_id', 'unknown'))}: {e.get('message', 'invalid')}"
            for e in errors
        )
        return {
            "validation_result": result,
            "validation_errors": error_text,
            "retry_count": state.get("retry_count", 0) + 1,
        }

    return {
        "validation_result": result,
        "validation_errors": None,
    }

Process Node

If validation passed, the order moves forward. In a real system this would write to your database, trigger fulfillment, or call another API:

def process_order(state: OrderState) -> dict:
    validation_id = state["validation_result"].get("validation_id", "")
    return {
        "final_result": (
            f"Order processed successfully.\n"
            f"Vendor: {state['extracted_data']['vendor']}\n"
            f"Amount: {state['extracted_data']['amount']} {state['extracted_data']['currency']}\n"
            f"Validation ID: {validation_id}"
        )
    }

The validation_id is a tamper-proof token from Flow — your downstream systems can verify that the data passed validation and hasn't been modified since.

Wiring the Graph

Now connect the nodes with conditional routing. If validation fails and we haven't exhausted retries, route back to the extract node with the error context:

from langgraph.graph import StateGraph, END

def should_retry(state: OrderState) -> str:
    if state.get("validation_errors") and state.get("retry_count", 0) < 3:
        return "retry"
    elif state.get("validation_errors"):
        return "give_up"
    return "proceed"

# Build the graph
graph = StateGraph(OrderState)

graph.add_node("extract", extract_order)
graph.add_node("validate", validate_order)
graph.add_node("process", process_order)

graph.set_entry_point("extract")
graph.add_edge("extract", "validate")

graph.add_conditional_edges(
    "validate",
    should_retry,
    {
        "retry": "extract",     # Back to extraction with error context
        "proceed": "process",   # Validation passed
        "give_up": END,         # Max retries reached
    },
)
graph.add_edge("process", END)

app = graph.compile()

Running It

result = app.invoke({
    "user_request": "Process an order from Globex Corp for twelve thousand five hundred dollars USD, PO number PO-2026-042",
    "retry_count": 0,
})

print(result["final_result"])

Output:

Order processed successfully.
Vendor: Globex Corp
Amount: 12500.0 USD
Validation ID: v_abc123...

The Self-Correction Loop

The interesting part is what happens when the LLM makes a mistake. Say it extracts currency: "Dollars" instead of "USD". Flow returns:

{
  "status": "validation_failed",
  "errors": [
    {"field": "currency", "message": "must be one of: USD, EUR, GBP, INR"}
  ]
}

The graph routes back to the extract node, which now includes the error in its prompt. The LLM reads "currency must be one of: USD, EUR, GBP, INR", fixes its extraction to "USD", and the second attempt passes validation.

This happens automatically — no human intervention, no hardcoded fixes. The LLM uses the structured error feedback from Flow to correct itself.

In our testing, most validation issues resolve in one retry. The retry_count cap of 3 is a safety net — if the agent can't fix it in three attempts, something is fundamentally wrong with the input and it's better to fail explicitly.

Why Not Just Use Pydantic in the Node?

You could validate with Pydantic directly in the extract node. For a single agent, that works fine. But Flow gives you a few things Pydantic doesn't:

Business rules that cross fields. Pydantic validates field types and constraints, but expressions like endDate > startDate or quantity * price == total need custom validators. Flow evaluates these as expressions — you configure them in the dashboard, no code changes needed.

Centralized validation across agents. If you have five different LangGraph pipelines submitting orders, they all validate against the same gate. Change a rule once, it applies everywhere. With Pydantic, you'd need to update the model in every repo.

Observability. Flow's analytics dashboard shows you which fields fail most often, which business rules trigger, and which agents (by session) are producing the most errors. When you're debugging why Agent C keeps submitting bad currencies, this is where you look.

Approval workflows. For high-value orders, add a human approval step on the gate. The pipeline pauses, a reviewer approves or rejects, and the graph resumes. You can't do this with a Pydantic validator.

Adding MCP for Direct Tool Access

If you want the LLM to call Flow tools directly (instead of going through a hardcoded REST call), you can use LangChain's MCP tool integration. Flow's MCP endpoint at https://api.rynko.dev/api/flow/mcp auto-generates a validate_{gate_slug} tool for each active gate in your workspace.

This means the LLM can discover available gates and submit payloads through tool calling, which is useful when the agent needs to decide which gate to validate against based on the input.

Local Development Setup

To set up a local LangGraph development environment:

# Create a project directory
mkdir langgraph-flow-demo && cd langgraph-flow-demo

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install langgraph langchain-openai httpx python-dotenv

# Create .env file
cat > .env << 'EOF'
OPENAI_API_KEY=sk-...
RYNKO_API_KEY=your_api_key_here
FLOW_GATE_ID=your_gate_id_here
EOF

Create a main.py with the code from this tutorial, add from dotenv import load_dotenv; load_dotenv() at the top, and run it with python main.py.

For iterative development, LangGraph has a built-in visualization tool:

# Print the graph structure
app.get_graph().print_ascii()

# Or save as PNG (requires pygraphviz)
app.get_graph().draw_png("graph.png")

This shows you the nodes, edges, and conditional routing at a glance — useful for verifying the self-correction loop is wired correctly.

Full Working Example

The complete code for this tutorial — including the graph, Flow client, .env.example, and two test scenarios — is in our developer resources repo. Clone it, add your API keys, and run python src/main.py.

Resources:

• Rynko Flow documentation

• Flow API reference

• LangGraph documentation

• Sign up for free — 500 Flow runs/month, no credit card

• Self-correction demo (terminal recording)

Most CrewAI tutorials skip this part. The output comes back as a string, maybe you parse it as JSON, and you hope it's correct. In production, that hope turns into bugs.

I've been using Rynko Flow as the validation layer after CrewAI tasks. The agent does its work, the output goes through a Flow gate that checks schema and business rules, and only validated data moves forward. When validation fails, the error response is structured enough that the agent can fix itself and retry.

What We're Building

A CrewAI crew with two agents:

1. Order Processor — Takes a natural language order request and extracts structured data

2. Validator — Submits the extracted data to a Rynko Flow gate, handles errors, and retries if needed

The validator agent uses a custom tool that wraps the Flow API, so it gets structured validation errors directly in its tool response.

Setup

pip install crewai httpx

You'll need:

• A Rynko account (free tier is fine)

• A Flow gate with your schema (setup guide)

• An OpenAI API key (CrewAI's default LLM)

The Flow Validation Tool

CrewAI agents use tools — Python functions decorated with @tool. Here's one that submits data to a Flow gate and returns the result in a format the LLM can reason about:

import os
import json
import httpx
from crewai.tools import tool

RYNKO_BASE_URL = os.environ.get("RYNKO_BASE_URL", "https://api.rynko.dev/api")
RYNKO_API_KEY = os.environ["RYNKO_API_KEY"]
GATE_ID = os.environ["FLOW_GATE_ID"]

@tool("validate_order")
def validate_order(order_json: str) -> str:
    """Validate an order payload against the Flow gate.
    Input must be a JSON string with fields: vendor (string),
    amount (number), currency (USD/EUR/GBP/INR), po_number (optional string).
    Returns validation result with status and any errors."""

    try:
        payload = json.loads(order_json)
    except json.JSONDecodeError as e:
        return json.dumps({"success": False, "error": f"Invalid JSON: {e}"})

    response = httpx.post(
        f"{RYNKO_BASE_URL}/flow/gates/{GATE_ID}/runs",
        json={"payload": payload},
        headers={
            "Authorization": f"Bearer {RYNKO_API_KEY}",
            "Content-Type": "application/json",
        },
        timeout=30,
    )

    result = response.json()

    if result.get("status") == "validation_failed":
        errors = result.get("error", {}).get("details", [])
        error_lines = [f"- {e.get('field', e.get('rule_id', 'unknown'))}: {e.get('message')}" for e in errors]
        return json.dumps({
            "success": False,
            "status": "validation_failed",
            "errors": error_lines,
            "message": "Fix these errors and resubmit.",
        }, indent=2)

    return json.dumps({
        "success": True,
        "status": result.get("status"),
        "run_id": result.get("runId"),
        "validation_id": result.get("validation_id"),
    }, indent=2)

The tool returns structured JSON in both success and failure cases. When validation fails, the error messages are specific enough — "currency must be one of: USD, EUR, GBP, INR" — that the LLM can fix the issue without guessing.

Defining the Agents

from crewai import Agent

order_processor = Agent(
    role="Order Processor",
    goal="Extract structured order data from customer requests accurately",
    backstory=(
        "You are an order processing specialist. You extract vendor name, "
        "amount, currency, and PO number from natural language requests. "
        "You output clean JSON with fields: vendor, amount, currency, po_number. "
        "Currency must be a 3-letter code (USD, EUR, GBP, or INR)."
    ),
    verbose=True,
    allow_delegation=False,
)

order_validator = Agent(
    role="Order Validator",
    goal="Validate extracted orders against business rules and fix any issues",
    backstory=(
        "You validate order data by submitting it to the validation gateway. "
        "If validation fails, you read the error messages carefully, fix each "
        "issue in the JSON, and resubmit. You keep trying until it passes or "
        "you've made 3 attempts. Always report the final validation status."
    ),
    tools=[validate_order],
    verbose=True,
    allow_delegation=False,
)

The validator agent has the Flow tool and explicit instructions to read errors and retry. CrewAI agents follow their backstory closely, so the self-correction behavior comes from the backstory rather than from framework-level retry logic.

Defining the Tasks

from crewai import Task

extract_task = Task(
    description=(
        "Extract order data from this customer request:\n\n"
        "{user_request}\n\n"
        "Output a JSON object with fields: vendor (string), amount (number), "
        "currency (3-letter code: USD, EUR, GBP, or INR), po_number (string, optional). "
        "Output ONLY the JSON, nothing else."
    ),
    expected_output="A JSON object with vendor, amount, currency, and optional po_number",
    agent=order_processor,
)

validate_task = Task(
    description=(
        "Take the order JSON from the previous task and validate it using the "
        "validate_order tool. If validation fails, read the error messages, fix "
        "the JSON, and call the tool again with corrected data. "
        "Report the final run ID and validation status."
    ),
    expected_output="Validation result with run ID and status (validated or failed)",
    agent=order_validator,
    context=[extract_task],
)

The context=[extract_task] tells CrewAI to pass the output of the extract task to the validator. The validator then takes that JSON and runs it through Flow.

Running the Crew

from crewai import Crew, Process

crew = Crew(
    agents=[order_processor, order_validator],
    tasks=[extract_task, validate_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff(
    inputs={
        "user_request": (
            "We need to process an order from Globex Corp for "
            "twelve thousand five hundred dollars, PO number PO-2026-042"
        )
    }
)

print("\n--- Final Result ---")
print(result)

What Happens at Runtime

When you run this, the output shows the full agent reasoning:

[Order Processor] Extracting order data...
> {"vendor": "Globex Corp", "amount": 12500, "currency": "USD", "po_number": "PO-2026-042"}

[Order Validator] Validating order...
> Using tool: validate_order
> Tool result: {"success": true, "status": "validated", "run_id": "..."}

--- Final Result ---
Order validated successfully. Run ID: 550e8400-...

Now here's the interesting case. Say the processor extracts currency: "Dollars":

[Order Validator] Validating order...
> Using tool: validate_order
> Tool result: {"success": false, "errors": ["- currency: must be one of: USD, EUR, GBP, INR"]}

[Order Validator] The currency is invalid. Fixing to "USD" and resubmitting...
> Using tool: validate_order
> Tool result: {"success": true, "status": "validated", "run_id": "..."}

The validator reads the error, fixes the currency, and resubmits. One retry, no human involved.

Handling Multiple Agents Writing to the Same Gate

CrewAI shines when you have multiple specialized agents. In a more complex setup, you might have separate crews for different order types — one for domestic orders, one for international, one for recurring subscriptions. All three can validate against the same Flow gate.

# Different crews, same validation gate
domestic_crew = Crew(agents=[domestic_processor, validator], ...)
international_crew = Crew(agents=[intl_processor, validator], ...)
subscription_crew = Crew(agents=[sub_processor, validator], ...)

The gate enforces consistent validation regardless of which crew produced the data. If you change a business rule — say, increasing the minimum order amount from \(10 to \)50 — you update it once in the Flow dashboard and every crew picks it up immediately.

Flow's analytics dashboard shows validation results by session, so you can see which crew or agent is producing the most errors and needs prompt tuning.

Adding Human Approval

For high-value orders, configure the gate's approval mode to require human review. When the validator submits a $50,000 order, Flow holds it in a review_required state instead of auto-approving. A reviewer gets an email, reviews the payload, and approves or rejects.

Your CrewAI task can poll for the approval result:

@tool("wait_for_approval")
def wait_for_approval(run_id: str) -> str:
    """Poll a Flow run until it reaches a terminal state."""
    for _ in range(60):
        response = httpx.get(
            f"{RYNKO_BASE_URL}/flow/runs/{run_id}",
            headers={"Authorization": f"Bearer {RYNKO_API_KEY}"},
            timeout=30,
        )
        status = response.json().get("status")
        if status in ("approved", "rejected", "completed", "delivered"):
            return json.dumps({"status": status, "run_id": run_id})
        time.sleep(5)
    return json.dumps({"status": "timeout", "run_id": run_id})

Using MCP Instead of REST

If you prefer the agent to discover Flow gates dynamically through tool calling (rather than hardcoding the gate ID), you can connect CrewAI to Flow's MCP endpoint. Flow auto-generates a validate_{gate_slug} tool for each active gate, and the tool schema includes field types and constraints so the LLM knows what to submit.

This is useful when your agents work across multiple gates and need to pick the right one based on context.

Local Development Setup

# Create project
mkdir crewai-flow-demo && cd crewai-flow-demo
python -m venv .venv
source .venv/bin/activate

# Install
pip install crewai httpx python-dotenv

# Environment
cat > .env << 'EOF'
OPENAI_API_KEY=sk-...
RYNKO_API_KEY=your_api_key_here
FLOW_GATE_ID=your_gate_id_here
EOF

Create main.py with the code above, add from dotenv import load_dotenv; load_dotenv() at the top, and run with python main.py. CrewAI's verbose=True shows you the full agent reasoning — useful for debugging prompt issues.

Full Working Example

The complete code — agents, tools, tasks, .env.example, and two test scenarios — is in our developer resources repo. Clone it, add your API keys, and run python src/main.py.

Resources:

• Rynko Flow documentation

• CrewAI documentation

• Sign up for free — 500 Flow runs/month, no credit card

• Self-correction demo (terminal recording)

So, we built Flow.

What Flow Does

Rynko Flow is a validation gateway that sits between your AI agent and your downstream systems. You define a gate with a schema and business rules, your agent submits payloads to it, and Flow validates the data before it moves forward. If the payload fails, the agent gets a clear error response it can act on. If it passes, Flow returns a tamper-proof validation_id that downstream systems can verify to confirm the data hasn't been modified in transit.

The pipeline looks like this:

Each stage is independent. Schema validation checks field types, required fields, and constraints like min/max values and allowed enums. Business rules evaluate cross-field expressions — things like endDate > startDate or quantity * price == total. If you need a human to review before delivery, add an approval step with internal team members or external reviewers. Once everything passes, Flow delivers the payload to your webhook endpoints.

Gates, Not Middleware

A gate is a named validation checkpoint. It has a schema (the structure you expect), business rules (the constraints that cross fields), and optionally an approval configuration and delivery channels. Each gate gets its own API endpoint.

Creating a gate takes about a minute in the dashboard:

1. Open the Flow dashboard and click Create Gate

2. Name your gate — give it something descriptive like "Order Validation". Flow generates a URL-friendly slug automatically (order-validation)

3. Define the schema — use the schema builder to add fields. For an order gate, you'd add orderId (string, required), amount (number, required, min 0), currency (string, required, allowed values: USD/EUR/GBP), and customerEmail (string, required, email format). Each field has a type dropdown and constraint options — no JSON to write by hand

4. Add business rules — click Add Rule and write expressions like amount >= 10 with an error message ("Order amount must be at least $10"). The rule editor validates your expression as you type, so you know it'll work before you save

5. Save the gate — it's immediately active and ready to receive payloads

If you already have your data models defined in code, you don't have to recreate the schema manually. Flow supports importing schemas directly from Pydantic (Python) and Zod (TypeScript). In the schema builder, click Import Schema, pick the format, and paste the JSON Schema output from model_json_schema() (Pydantic) or zodToJsonSchema() (Zod). Flow maps the types, constraints, and required fields automatically. There's a full tutorial with code examples for both.

This means if you have a Pydantic model like:

class Order(BaseModel):
    order_id: str
    amount: float = Field(ge=0)
    currency: Literal["USD", "EUR", "GBP"]
    customer_email: EmailStr

You run Order.model_json_schema(), paste the output into the import dialog, and your gate schema is ready — field types, constraints, and all.

{
    "title": "Order",
    "type": "object",
    "properties": {
      "order_id": {
        "title": "Order Id",
        "type": "string"
      },
      "amount": {
        "title": "Amount",
        "type": "number",
        "minimum": 0
      },
      "currency": {
        "title": "Currency",
        "type": "string",
        "enum": ["USD", "EUR", "GBP"]
      },
      "customer_email": {
        "title": "Customer Email",
        "type": "string",
        "format": "email"
      }
    },
    "required": ["order_id", "amount", "currency", "customer_email"]
  }

When your agent submits a payload to this gate, the response tells you exactly what happened at each validation layer:

{
  "success": true,
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "validated",
  "validation_id": "v_abc123...",
  "layers": {
    "schema": "pass",
    "business_rules": "pass"
  }
}

If validation fails, the response includes specific error details — which field failed, which constraint was violated, which business rule returned false. The agent gets actionable feedback it can use to fix the data and resubmit.

Why This Matters for AI Agents

LLMs hallucinate. They produce plausible-looking data that might have an invalid enum value, a missing required field, or a number that violates a business constraint. When you're generating a single document, you catch these by eye. When an agent is processing hundreds of payloads autonomously, you need systematic validation.

The interesting thing we've seen in practice is that agents self-correct. When an MCP-connected agent submits a payload that fails validation, it reads the error response, fixes the issues, and resubmits — often without any human involvement. We ran tests where we intentionally gave agents incomplete or incorrect data, and the validation-resubmission loop resolved the issues in one or two attempts. (ref: Flow MCP — AI Agent Integration Test Report | Rynko Documentation)

Flow has a built-in circuit breaker for this pattern. If an agent (identified by its MCP session) keeps submitting payloads that fail the same gate, Flow backs off — first warning, then temporarily blocking submissions from that session. This prevents a malfunctioning agent from burning through your quota with an infinite retry loop. The circuit breaker tracks failures per gate per session, with configurable thresholds and cooldown periods.

Multi-Agent Workflows

https://asciinema.org/a/824113

Gates are the shared contract between these agents and your systems. A "Customer Order" gate doesn't care whether the payload comes from a single monolithic agent or from the last step in a five-agent chain — it validates the same schema and business rules regardless. This means you can swap agents, change your orchestration graph, or add new agents to the pipeline without touching your validation logic. The gate is stable while the agents evolve around it.

In practice, this plays out in a few ways:

Pipeline validation. An orchestrator runs Agent A (data extraction) → Agent B (enrichment) → Agent C (formatting), and the final output goes through a Flow gate before hitting your database. If Agent C produces bad data, the orchestrator gets structured errors it can route back to the responsible agent for correction — not a generic 400 from your API.

Parallel agents, same gate. Multiple agents process different inputs concurrently — say, ten order-processing agents each handling a different customer. They all submit to the same "Order Validation" gate. Flow validates each independently, the circuit breaker tracks failures per session so one misbehaving agent doesn't affect the others, and your downstream system only receives validated payloads.

Cross-agent consistency. When Agent A writes to the "Invoice" gate and Agent B writes to the "Payment" gate, and both gates have business rules referencing amount ranges and currency constraints, you get consistent validation across your entire agent fleet without encoding those rules in each agent's prompt.

The analytics dashboard makes this observable — you can see which agents (by session) are hitting which gates, what their failure rates look like, and which business rules are triggering most often. When you're running dozens of agents in production, this is how you find the one that's drifting.

Human-in-the-Loop When You Need It

Not everything should be auto-approved. For high-value transactions, sensitive data changes, or any scenario where you want a human to verify before the data moves downstream, Flow supports approval workflows.

You configure approvers on a gate — either team members who review from the dashboard, or external reviewers who get a magic link via email. External reviewers don't need a Rynko account. They click a link, see the payload, and approve or reject it. The magic links are HMAC-SHA256 signed, expire after 72 hours, and are single-use for approval actions.

The approval model is any-approves: the first approver to act determines the outcome. For high-volume gates, we batch notification emails into 5-minute digests so reviewers don't get buried in individual emails. There's also a hard safety cap of 30 emails per hour per approver to prevent notification fatigue.

The review experience for freetext content (Markdown, HTML, plain text) includes scroll-to-approve guardrails — the approve button stays disabled until the reviewer has scrolled through the entire content. For long documents, we auto-generate a table of contents from Markdown headers so reviewers can navigate quickly.

MCP Integration: Dynamic Tools per Gate

This is where Flow connects directly to the AI agent workflow. When you connect an AI tool (Claude Desktop, Cursor, VS Code, or any MCP client) to Flow's MCP endpoint at https://api.rynko.dev/api/flow/mcp, Flow auto-generates a validation tool for each active gate in your workspace.

A gate with slug order-validation becomes a tool called validate_order_validation. The tool's input schema is generated from the gate's current schema — each field becomes a typed JSON Schema property with its constraints. The tool description includes the gate's business rule error messages, so the agent understands the constraints before submitting.

When you update a gate's schema, Flow pushes a notifications/tools/list_changed event to connected agents. They automatically see the updated tool list without reconnecting. No redeploy, no config change.

A conversation with an MCP-connected agent might look like this:

You: Validate this order before submitting.

Agent: I'll validate it against your Order Validation gate.
       [calls validate_order_validation]

       The order passed validation:
       - Schema validation: pass
       - Business rules: pass
       - Validation ID: v_abc123...

       You can use the validation ID to confirm this data
       hasn't been modified when it reaches your order system.

Freetext Mode

Not all agent outputs are structured JSON. Sometimes the output is a Markdown document, an HTML email body, or a code snippet. Flow supports a freetext mode where the gate accepts content as a string instead of a structured schema.

Content format is declared at gate creation — plaintext, Markdown, HTML, or code. For Markdown and HTML content, Flow runs a sanitization pipeline on the backend using sanitize-html with a strict allowlist. Script tags, iframes, event handlers, and inline styles are stripped. Links get rel="noopener noreferrer". The reviewer sees sanitized content in a sandboxed view.

This is useful for agent workflows that produce reports, summaries, or email drafts where you need a human to review the content before it gets sent.

Delivery and Reliability

After validation (and approval, if configured), Flow delivers the payload to your webhook endpoints. Deliveries are signed with HMAC-SHA256 so you can verify the payload hasn't been tampered with.

The retry policy is straightforward: 5 attempts with delays at 30 seconds, 2 minutes, and 10 minutes. Each delivery attempt is logged, and failed deliveries can be retried manually from the dashboard or via the SDK.

Flow enforces per-team concurrency caps to keep the multi-tenant system fair — the exact limits scale with your tier, but even on the Scale plan, no single team can consume more than 25% of total worker concurrency. This prevents one team's spike from degrading service for everyone else.

SDKs

We've added Flow support to all three official SDKs. The pattern is the same across Node.js, Python, and Java — submit a run, poll for result, handle approvals:

import { Rynko } from '@rynko/sdk';

const client = new Rynko({ apiKey: process.env.RYNKO_API_KEY });

const run = await client.flow.submitRun('gate_abc123', {
  input: {
    orderId: 'ORD-2026-042',
    amount: 1250.00,
    currency: 'USD',
    customerEmail: 'buyer@example.com',
  },
});

const result = await client.flow.waitForRun(run.id, {
  pollInterval: 1000,
  timeout: 60000,
});

if (result.status === 'approved' || result.status === 'completed') {
  console.log('Validated:', result.validatedPayload);
} else if (result.status === 'validation_failed') {
  console.log('Errors:', result.errors);
}

The SDKs are at version 1.3.1 with 14 Flow methods covering gates (read-only), runs, approvals, and deliveries. All three SDKs include automatic retry with exponential backoff for rate limits and transient errors.

Pricing

Flow is a separate subscription from Rynko's document generation (Render). The pricing is based on validation runs per month:

The free tier is gate-limited to 3 — this is intentional. Most teams find they need more gates once they start connecting multiple agents to different validation checkpoints, and that's the natural upgrade trigger. Paid tiers have unlimited gates.

To celebrate the launch, we're opening a Founder's Preview — sign up today and get 3 months of the Growth tier (100,000 runs/month, unlimited gates) completely free. No credit card required, no commitment. Once the preview ends, you can stay on Growth or switch to any tier that fits your usage.

If you also need document generation, Render Packs are available as add-ons on any tier — \(19/month for 500 documents, \)49 for 2,000, or $119 for 10,000.

The Dashboard

Flow comes with a full web dashboard for managing gates, reviewing runs, handling approvals, and tracking analytics. The gate configurator includes a visual schema builder (with Pydantic and Zod import), a business rule editor with live expression validation, and approval/delivery configuration. The runs view shows real-time status updates, validation error breakdowns, and a timeline of each run's journey through the pipeline.

The analytics dashboard covers the metrics you'd expect — run outcomes by gate, top failing rules, approval rates and decision times, throughput over configurable periods, and circuit breaker health. These metrics help you tune your gates and catch systemic issues early.

Getting Started

1. Sign up for free — 500 Flow runs/month included, no credit card

2. Create a gate in the Flow dashboard — define your schema and business rules

3. Submit a test payload using the Quick Start guide or the dry-run endpoint (doesn't count against quota)

4. Connect your AI agent via the MCP endpoint — Claude Desktop, Cursor, VS Code, Windsurf, Zed, or Claude Code

Flow is live and production-ready. We've been running it internally for weeks and the architecture has handled sustained load without surprises. If you're building with AI agents and need a systematic way to validate their outputs before they reach downstream systems, this is what we built it for.

Sign up | Documentation | MCP Setup | API Reference

Questions or feedback: support@rynko.dev or Discord.

Since then, every major AI tool has added support for remote MCP servers over HTTP. Claude Desktop, Cursor, Windsurf, VS Code, Zed, and Claude Code all support connecting to a remote MCP endpoint with a URL and headers — no local process, no npm, no Node.js dependency.

So we've moved to remote-first and deprecated the standalone @rynko/mcp-server npm package.

What Changed

Our MCP server now runs as part of Rynko's backend infrastructure, exposed at two endpoints:

• Render MCP (templates and document generation): https://api.rynko.dev/api/mcp-documents

• Flow MCP (AI output validation): https://api.rynko.dev/api/flow/mcp

Both use Streamable HTTP transport — JSON-RPC 2.0 over HTTP with optional Server-Sent Events for real-time notifications. This is the same transport that Claude Desktop, Cursor, and other tools use natively.

The old npm package used stdio transport: it spawned a local Node.js process that communicated with your AI tool via stdin/stdout. This meant every user needed Node.js 18+, the package had to be downloaded and kept up to date, and any server-side improvements required a new npm release.

With remote HTTP, none of that applies. You point your AI tool at a URL, add an auth header, and you're connected. Updates happen server-side — no package to update.

Setup Is Now 30 Seconds

Here's what the config looks like for each tool:

Cursor

{
  "mcpServers": {
    "rynko": {
      "url": "https://api.rynko.dev/api/mcp-documents",
      "headers": {
        "Authorization": "Bearer pat_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

VS Code

{
  "servers": {
    "rynko": {
      "type": "http",
      "url": "https://api.rynko.dev/api/mcp-documents",
      "headers": {
        "Authorization": "Bearer pat_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code

claude mcp add --transport http rynko https://api.rynko.dev/api/mcp-documents \
  --header "Authorization: Bearer pat_xxxxxxxxxxxxxxxx"

Claude Desktop

Claude Desktop has a few options. The simplest is using Connectors with OAuth — go to Settings → Connectors, add a custom connector with the URL, and sign in with your Rynko account. No token management needed.

If you prefer using a PAT, use the mcp-remote proxy:

{
  "mcpServers": {
    "rynko": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.rynko.dev/api/mcp-documents",
        "--header",
        "Authorization:${RYNKO_PAT}"
      ],
      "env": {
        "RYNKO_PAT": "Bearer pat_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Full setup instructions for all six tools are in our Render MCP guide and Flow MCP guide.

Flow MCP: Why Remote Was Essential

When we built Rynko Flow — our AI output validation gateway — we needed dynamic tool registration. Each validation gate in your workspace generates a dedicated validate_{slug} tool with a schema derived from the gate's configuration. When you create, update, or delete a gate, the MCP server pushes a notifications/tools/list_changed event so connected agents see the updated tool list without reconnecting.

This kind of server-initiated push notification is only possible with remote transport. A stdio server can't push events to the client — it can only respond to requests. We would have needed to implement polling or some other workaround, and the developer experience would have been worse.

Going remote-first meant Flow MCP worked naturally from day one, with real-time tool discovery and no compromises.

What Happens to the npm Package

The @rynko/mcp-server package on npm still works, but we've marked it as deprecated. It only supports Render tools (template management and document generation) — Flow tools were never added to it because they require server-side event support.

If you're currently using the npm package, switching to the remote server takes about a minute: replace the command/args/env config with a url/headers config pointing to https://api.rynko.dev/api/mcp-documents. Your PAT token works the same way — just pass it as a Bearer token in the Authorization header.

What We Gained

Moving to remote MCP simplified things on both sides:

For users: No Node.js dependency, no npm package to install or update, no PATH issues, no local process to debug. Just a URL and a token.

For us: One deployment target instead of coordinating npm releases with backend changes. Server-side improvements are available to everyone immediately. And we can use features like SSE for real-time notifications that stdio doesn't support.

The MCP ecosystem is still young, but the direction is clear — remote HTTP transport is becoming the standard. We're glad we made the move early.

Resources:

• Render MCP Setup Guide

• Flow MCP Setup Guide

• Sign up for free

It's a feature request that shows up in every SaaS app eventually: "Can I download this as a PDF?"

Users want to export dashboards, download invoices, save reports, and share formatted documents. And as a developer, you know this means dealing with PDF generation — one of those tasks that sounds simple but turns into a rabbit hole of browser dependencies, layout quirks, and maintenance headaches.

This guide shows you how to add PDF (and Excel) export to your SaaS in an afternoon using Rynko, without adding Puppeteer to your stack.

The Traditional Approach (and Why It Hurts)

Most teams approach PDF export like this:

1. Create an HTML template with Handlebars/EJS

2. Add Puppeteer or Playwright as a dependency

3. Spin up a headless Chrome instance

4. Render the HTML and export to PDF

5. Handle Chrome memory leaks, version conflicts, and cold start times

6. Scale the whole thing when you have more than a few concurrent exports

The result is a PDF service that:

• Takes 3-8 seconds per document

• Requires 200-500MB RAM per Chrome instance

• Breaks when Chrome auto-updates

• Needs its own scaling strategy

• Makes your Docker images huge

And when product asks "can we also export as Excel?" — you start from scratch because Puppeteer doesn't do spreadsheets.

The Rynko Approach

Instead, you design a template once (visual editor or API), and call our SDK to generate documents. No browser. Sub-500ms generation. PDF and Excel from the same template.

Here's the full integration pattern.

Step 1: Design Your Templates

Before writing any code, create the templates your users will need. Common SaaS export templates:

Use the visual designer at app.rynko.dev to build each template. Define variables that match your application's data model.

For example, a "Usage Report" template might have these variables:

interface UsageReportVariables {
  accountName: string;
  reportPeriod: string;
  totalApiCalls: number;
  totalDocuments: number;
  storageUsedMb: number;
  dailyUsage: Array<{ date: string; apiCalls: number; documents: number }>;
  topEndpoints: Array<{ endpoint: string; calls: number; avgLatencyMs: number }>;
}

Step 2: Create a Document Service

Add a thin service layer that handles document generation:

// src/services/document.service.ts
import { Rynko } from '@rynko/sdk';

const rynko = new Rynko({ apiKey: process.env.RYNKO_API_KEY! });

// Template IDs - map to your Rynko templates
const TEMPLATES = {
  invoice: 'invoice',
  usageReport: 'usage-report',
  dataExport: 'data-export',
  dashboardSummary: 'dashboard-summary',
} as const;

type TemplateKey = keyof typeof TEMPLATES;

interface GenerateOptions {
  template: TemplateKey;
  variables: Record<string, any>;
  format?: 'pdf' | 'excel';
  filename?: string;
}

export async function generateDocument(options: GenerateOptions) {
  const { template, variables, format = 'pdf' } = options;
  const params = { templateId: TEMPLATES[template], variables };

  const job = format === 'excel'
    ? await rynko.documents.generateExcel(params)
    : await rynko.documents.generatePdf(params);

  const completed = await rynko.documents.waitForCompletion(job.jobId);

  if (completed.status !== 'completed') {
    throw new Error(`Document generation failed: ${completed.errorMessage}`);
  }

  return {
    downloadUrl: completed.downloadUrl,
    jobId: job.jobId,
    format,
  };
}

Step 3: Add API Endpoints

Express / Node.js

// src/routes/exports.ts
import { Router } from 'express';
import { generateDocument } from '../services/document.service';
import { requireAuth } from '../middleware/auth';

const router = Router();

// Download invoice as PDF
router.get('/invoices/:id/pdf', requireAuth, async (req, res) => {
  const invoice = await db.invoices.findById(req.params.id);

  if (!invoice || invoice.accountId !== req.user.accountId) {
    return res.status(404).json({ error: 'Invoice not found' });
  }

  const result = await generateDocument({
    template: 'invoice',
    format: 'pdf',
    variables: {
      invoiceNumber: invoice.number,
      date: invoice.date,
      customerName: invoice.customerName,
      items: invoice.lineItems,
      subtotal: invoice.subtotal,
      tax: invoice.tax,
      total: invoice.total,
    },
  });

  res.json({ downloadUrl: result.downloadUrl });
});

// Download usage report (PDF or Excel)
router.get('/reports/usage', requireAuth, async (req, res) => {
  const format = req.query.format === 'excel' ? 'excel' : 'pdf';
  const period = req.query.period as string || 'current-month';

  const usage = await db.usage.getReport(req.user.accountId, period);

  const result = await generateDocument({
    template: 'usageReport',
    format,
    variables: {
      accountName: req.user.accountName,
      reportPeriod: usage.periodLabel,
      totalApiCalls: usage.totalApiCalls,
      totalDocuments: usage.totalDocuments,
      storageUsedMb: usage.storageUsedMb,
      dailyUsage: usage.dailyBreakdown,
      topEndpoints: usage.topEndpoints,
    },
  });

  res.json({ downloadUrl: result.downloadUrl });
});

// Generic data export
router.post('/exports', requireAuth, async (req, res) => {
  const { type, filters, format = 'pdf' } = req.body;
  const data = await db.exports.getData(req.user.accountId, type, filters);

  const result = await generateDocument({
    template: 'dataExport',
    format,
    variables: {
      exportTitle: `${type} Export`,
      exportDate: new Date().toISOString().split('T')[0],
      columns: data.columns,
      rows: data.rows,
      totalRows: data.totalRows,
    },
  });

  res.json({ downloadUrl: result.downloadUrl });
});

export default router;

Next.js API Routes

// app/api/invoices/[id]/pdf/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { generateDocument } from '@/lib/document-service';
import { getServerSession } from 'next-auth';

export async function GET(req: NextRequest, { params }: { params: { id: string } }) {
  const session = await getServerSession();
  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

  const invoice = await db.invoices.findById(params.id);
  if (!invoice) return NextResponse.json({ error: 'Not found' }, { status: 404 });

  const result = await generateDocument({
    template: 'invoice',
    format: 'pdf',
    variables: mapInvoiceToVariables(invoice),
  });

  return NextResponse.json({ downloadUrl: result.downloadUrl });
}

Step 4: Add Frontend Download Buttons

// components/DownloadButton.tsx
'use client';

import { useState } from 'react';
import { Download, FileSpreadsheet } from 'lucide-react';

interface DownloadButtonProps {
  endpoint: string;
  format: 'pdf' | 'excel';
  label?: string;
}

export function DownloadButton({ endpoint, format, label }: DownloadButtonProps) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleDownload = async () => {
    setLoading(true);
    setError(null);
    try {
      const res = await fetch(`\({endpoint}?format=\){format}`);
      if (!res.ok) throw new Error('Export failed');
      const { downloadUrl } = await res.json();
      window.open(downloadUrl, '_blank');
    } catch (err) {
      setError('Export failed. Please try again.');
    } finally {
      setLoading(false);
    }
  };

  const Icon = format === 'excel' ? FileSpreadsheet : Download;
  const text = label || `Download ${format.toUpperCase()}`;

  return (
    <div>
      <button onClick={handleDownload} disabled={loading} className="btn btn-secondary">
        <Icon className="h-4 w-4 mr-2" />
        {loading ? 'Generating...' : text}
      </button>
      {error && <p className="text-sm text-red-500 mt-1">{error}</p>}
    </div>
  );
}

Usage in your pages:

// In your invoice detail page
<DownloadButton endpoint={`/api/invoices/${invoice.id}/pdf`} format="pdf" />

// In your reports page — offer both formats
<div className="flex gap-2">
  <DownloadButton endpoint="/api/reports/usage" format="pdf" label="PDF Report" />
  <DownloadButton endpoint="/api/reports/usage" format="excel" label="Excel Export" />
</div>

Step 5: Handle Background Generation (Optional)

For large reports or batch exports, use webhooks instead of waiting synchronously:

// Start generation without waiting
export async function queueDocumentGeneration(options: GenerateOptions & { userId: string }) {
  const params = {
    templateId: TEMPLATES[options.template],
    variables: options.variables,
  };

  const job = options.format === 'excel'
    ? await rynko.documents.generateExcel(params)
    : await rynko.documents.generatePdf(params);

  // Store the job reference
  await db.exportJobs.create({
    jobId: job.jobId,
    userId: options.userId,
    status: 'processing',
  });

  return job.jobId;
}

// Webhook handler — called when document is ready
import { verifyWebhookSignature } from '@rynko/sdk';

app.post('/webhooks/rynko', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = verifyWebhookSignature({
    payload: req.body.toString(),
    signature: req.headers['x-rynko-signature'] as string,
    secret: process.env.RYNKO_WEBHOOK_SECRET!,
  });

  if (event.type === 'document.generated') {
    await db.exportJobs.update(event.data.jobId, {
      status: 'completed',
      downloadUrl: event.data.downloadUrl,
    });

    // Notify user (in-app notification, email, etc.)
    await notifyUser(event.data.metadata.userId, {
      title: 'Your export is ready',
      downloadUrl: event.data.downloadUrl,
    });
  }

  res.json({ received: true });
});

What This Gets You

After an afternoon of integration:

• PDF export on any page that displays data

• Excel export from the same templates — no separate implementation

• Sub-500ms generation — users don't wait

• No browser dependencies — no Puppeteer, no Chrome, no memory issues

• Template changes without deploys — update templates in the visual editor, no code changes needed. Stop wasting engineering sprints on "Can we move the logo 5px to the left?" — give the visual editor to your designer and never touch the PDF code again.

• Non-developers can update templates — product or design teams can modify document layouts directly

Cost at Scale

Compare that to Puppeteer infrastructure costs at scale, plus the engineering time to maintain it.

Get Started

1. Sign up for Rynko — free with 5,000 credits

2. Design your export templates in the visual editor

3. npm install @rynko/sdk (or pip install rynko)

4. Add the document service and API endpoints

5. Add download buttons to your frontend

Your users get their PDF exports. You get your afternoon back.

Get Started Free | SDK Documentation | API Reference

New to Rynko? Follow our Getting Started in 5 Minutes guide. Want to understand the rendering architecture? Read Design Once, Generate Anywhere.

Building something specific? Check our use cases for industry-specific examples and templates.

_{Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.}

Puppeteer comes up in almost every conversation about PDF generation. It's battle-tested, well-documented, and most developers already know HTML and CSS. When I started building Rynko, I didn't set out to replace Puppeteer — I set out to solve a different problem. But the two tools end up on the same shortlists, so it's worth laying out where they overlap, where they diverge, and when each one makes sense.

How They Work (Side by Side)

The architectural difference between Puppeteer and Rynko isn't just an implementation detail — it drives almost every other tradeoff between the two.

Puppeteer's pipeline looks like this: your application generates HTML (usually from a template engine like Handlebars or EJS), launches a headless Chrome instance, loads the HTML into a page, waits for rendering to complete, and calls page.pdf() to export the result. The PDF you get is essentially a print of a web page.

HTML + CSS → Headless Chrome → Page Render → PDF Export

Rynko's pipeline skips the browser entirely. Templates are defined as a structured JSON component tree — not HTML. The Yoga layout engine (the same flexbox engine that powers React Native) computes every element's position, and PDFKit writes native vector primitives directly to the PDF. Text is rendered as searchable glyphs, charts as Bezier paths, fonts are embedded.

JSON Template + Variables → Yoga Layout → PDFKit → Native PDF

The key insight: Puppeteer renders a browser page and then exports it. Rynko builds the PDF directly, with no intermediate rendering step. This distinction shows up in performance, resource usage, deployment complexity, and output consistency.

The Performance Gap

I'll be upfront — performance is where the difference is most dramatic, and the numbers aren't close.

Generation speed. A typical Puppeteer document takes 3–8 seconds to generate. That includes Chrome startup (or page creation if you're reusing a browser instance), HTML rendering with CSS layout, font loading, and the PDF export step. Rynko generates the same document in 200–500ms. The Yoga layout pass is fast because it's computing flexbox positions in native code, and PDFKit writes PDF primitives without a browser rendering step in between.

Memory. Each Chrome instance needs 200–500MB of RAM. If you're generating documents concurrently, that adds up fast — 10 concurrent PDFs can consume 2–5GB. Rynko's workers use roughly 50MB each, because there's no browser process to keep alive.

Serverless reality. This is where Puppeteer hits its hardest wall. AWS Lambda has a 250MB deployment package limit — Chrome alone is roughly 280MB compressed. Cold starts add 5–15 seconds on top of the generation time. Most teams that start with Puppeteer on Lambda eventually move to dedicated instances, which changes the cost equation significantly. Because Rynko's renderer has no browser dependency, it fits comfortably in serverless environments without special packaging or layer configurations.

What Puppeteer Does Better

I want to be fair about this, because Puppeteer has real strengths that matter for certain use cases.

Full CSS support. Puppeteer renders in a real browser, which means you get the complete CSS specification — grid, flexbox, animations (for screenshots), web fonts via @font-face, media queries, and CSS @page rules. Rynko's layout engine supports flexbox-style positioning through Yoga, but it's not a browser. If your templates rely heavily on CSS grid or advanced selectors, Puppeteer handles that natively.

Existing HTML templates work as-is. If you have a Handlebars, EJS, or React-based template pipeline that's already producing the HTML you want, Puppeteer plugs directly into it. No conversion, no new template format. That's a real advantage when you've already invested in HTML templates.

URL-to-PDF and screenshots. Puppeteer can navigate to a URL and export what it sees. That's useful for capturing web pages, generating screenshots of dashboards, or turning existing web content into PDFs without modifying the source. Rynko doesn't do this — it generates documents from structured templates, not from URLs.

Mature ecosystem. Puppeteer has been around since 2017. It has extensive documentation, a large community, hundreds of Stack Overflow answers, and well-understood patterns for common problems. When something goes wrong, you'll find someone who's already solved it.

Free and open source. There's no subscription, no usage limits, no vendor dependency. You own the entire pipeline.

What Rynko Does Better

Speed and resource efficiency. As covered above, the performance gap is significant. For latency-sensitive workloads — a user clicks "Download Invoice" and waits — 200ms vs 5 seconds is the difference between a smooth experience and a loading spinner.

PDF and Excel from the same template. This is the biggest practical difference. Puppeteer generates PDFs only. If you also need Excel output — and most business applications eventually do — you're building and maintaining a completely separate pipeline with a library like ExcelJS. With Rynko, you design one template and generate both formats from the same API call by changing a single parameter.

// Same template, same data — just change the method
const pdf = await rynko.documents.generatePdf({
  templateId: 'invoice',
  variables: invoiceData,
});

const excel = await rynko.documents.generateExcel({
  templateId: 'invoice',
  variables: invoiceData,
});

Visual designer for non-developers. Templates are designed in a web-based drag-and-drop editor. Product managers, finance teams, and operations people can update a template without a code deploy. With Puppeteer, every layout change — moving a logo, adjusting a font size, adding a column — requires a developer to modify HTML.

28 built-in component types. Tables, charts (8 types), QR codes, barcodes, 9 interactive PDF form field types (text inputs, checkboxes, dropdowns, digital signatures), conditional blocks, loops, and key-value layouts. These are first-class components with property schemas validated at design time, not HTML you have to build and style yourself.

AI template creation via MCP. Rynko provides an MCP server that lets AI agents like Claude Desktop, Cursor, or any MCP-compatible client create templates and generate documents through conversation. The structured JSON schema gives the AI a well-defined contract to work against — it can't produce broken HTML or invalid CSS because the schema is validated before it reaches the renderer. This is a fundamentally different situation from asking an LLM to generate valid HTML templates, where broken tags and layout issues are common and hard to catch before rendering.

No browser dependency. No Chrome to install, no Puppeteer version to pin, no --no-sandbox flags in Docker, no Chromium packages to maintain in your CI/CD pipeline. The renderer is a Node.js library with no native browser dependencies.

Zero XSS surface. Templates are JSON, not HTML. There's no innerHTML, no script injection vector, no CSS expression() attack surface. The expression evaluator uses a strict allowlist — arithmetic, comparisons, Math.* functions, and safe array methods like .map(), .reduce(), .filter(). Calls to eval(), require(), prototype access, and template literals are blocked at the syntax level.

Deterministic rendering. This is one the biggest strengths of Rynko. The same template and data produce identical output regardless of the host environment. There's no CSS cascade, no browser rendering differences between your development machine and a Linux container in production. Chrome version updates can't silently change your document output.

The Excel Question

This deserves its own section because it's the single most common reason teams switch from Puppeteer to Rynko.

Puppeteer generates PDFs. That's it. When your finance team asks for an Excel version of the same invoice, or your clients need spreadsheet exports they can manipulate, you're building a second generation pipeline. That typically means ExcelJS or SheetJS, with its own template logic, its own styling code (cell-by-cell formatting, manual column widths), and its own maintenance burden. Two codebases for the same document.

// With Puppeteer, you need two completely separate pipelines:

// Pipeline 1: PDF via Puppeteer
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent(invoiceHtml);
const pdf = await page.pdf({ format: 'A4' });
await browser.close();

// Pipeline 2: Excel via ExcelJS (separate library, separate logic)
const workbook = new ExcelJS.Workbook();
const sheet = workbook.addWorksheet('Invoice');
sheet.columns = [
  { header: 'Description', key: 'description', width: 30 },
  { header: 'Qty', key: 'qty', width: 10 },
  { header: 'Price', key: 'price', width: 15 },
];
invoice.items.forEach(item => sheet.addRow(item));
// Now manually style every cell, add borders, format numbers...
await workbook.xlsx.writeFile('invoice.xlsx');

With Rynko, it's the same template, the same API, the same data. The rendering engine handles format-specific output — tables become Excel sheets with proper column types, number formatting carries over, charts render natively in both formats. When you update the template, both outputs update together.

If your application only ever needs PDF, this isn't a factor. But in my experience building enterprise systems, Excel comes up eventually — and rebuilding later is significantly more expensive than choosing a tool that handles both from the start.

Code Comparison: Generating an Invoice

Here's what generating the same invoice looks like with each tool, end to end.

Puppeteer

import puppeteer from 'puppeteer';
import Handlebars from 'handlebars';

// Step 1: Define your HTML template (or load from a file)
const templateSource = `
<html>
<style>
  body { font-family: Arial; padding: 40px; }
  table { width: 100%; border-collapse: collapse; margin-top: 20px; }
  th { background: #f4f4f4; text-align: left; }
  th, td { padding: 8px; border-bottom: 1px solid #ddd; }
  .total { font-weight: bold; text-align: right; margin-top: 20px; font-size: 18px; }
  .header { display: flex; justify-content: space-between; }
</style>
<body>
  <div class="header">
    <div>
      <h1>{{companyName}}</h1>
      <p>{{companyEmail}}</p>
    </div>
    <div>
      <h2>Invoice #{{invoiceNumber}}</h2>
      <p>Date: {{invoiceDate}}</p>
    </div>
  </div>
  <p>Bill to: {{clientName}}</p>
  <table>
    <thead>
      <tr><th>Description</th><th>Hours</th><th>Rate</th><th>Amount</th></tr>
    </thead>
    <tbody>
      {{#each lineItems}}
      <tr>
        <td>{{description}}</td>
        <td>{{hours}}</td>
        <td>${{rate}}</td>
        <td>${{multiply hours rate}}</td>
      </tr>
      {{/each}}
    </tbody>
  </table>
  <p class="total">Total: ${{total}}</p>
</body>
</html>
`;

// Step 2: Compile and render the HTML
Handlebars.registerHelper('multiply', (a, b) => a * b);
const template = Handlebars.compile(templateSource);
const html = template(invoiceData);

// Step 3: Launch Chrome, render, and export
const browser = await puppeteer.launch({
  args: ['--no-sandbox', '--disable-setuid-sandbox'],
});
const page = await browser.newPage();
await page.setContent(html, { waitUntil: 'networkidle0' });
const pdf = await page.pdf({
  format: 'A4',
  printBackground: true,
  margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' },
});
await browser.close();

You're responsible for: the HTML template, the CSS styling, Handlebars helpers for calculations, Chrome lifecycle management, and error handling when Chrome crashes or runs out of memory.

Rynko

import { Rynko } from '@rynko/sdk';

const rynko = new Rynko({ apiKey: process.env.RYNKO_API_KEY! });

// Template is designed in the visual editor — layout, styling,
// and calculated fields (subtotals, tax) live in the template
const job = await rynko.documents.generatePdf({
  templateId: 'invoice',
  variables: {
    companyName: 'Delivstat Consulting',
    companyEmail: 'billing@delivstat.com',
    invoiceNumber: 'INV-2026-0042',
    invoiceDate: '2026-02-23',
    clientName: 'Acme Technologies Pvt. Ltd.',
    lineItems: [
      { description: 'Technical Consulting', hours: 24, rate: 150 },
      { description: 'API Design & Review', hours: 16, rate: 150 },
      { description: 'Performance Optimization', hours: 12, rate: 175 },
    ],
    taxRate: 0.18,
    taxLabel: 'GST (18%)',
  },
});

const result = await rynko.documents.waitForCompletion(job.jobId);
console.log(result.downloadUrl);

The template handles layout, styling, and calculations like subtotals and tax amounts through built-in expression support (e.g., lineItems.reduce((sum, item) => sum + item.hours * item.rate, 0)). Your application code just sends the data.

When to Use Each

When Puppeteer makes sense

• You have existing HTML templates and they work well. If your Handlebars or EJS pipeline already produces good PDFs and you don't need Excel, there's no reason to migrate.

• You need URL-to-PDF capture. Puppeteer can navigate to a page and export it. Rynko generates documents from templates, not from URLs.

• Full CSS is required. If your templates use CSS grid, advanced selectors, or browser-specific features that Yoga's flexbox model doesn't cover, Puppeteer gives you the full browser engine.

• Budget is the primary constraint. Puppeteer is free. If you have the engineering time to manage the infrastructure and Chrome dependencies, the licensing cost is zero.

• Low volume, latency doesn't matter. If you're generating a handful of documents per day in a background job, the 3–8 second generation time may not be a problem worth solving.

When Rynko makes sense

• You're starting fresh. If you don't have existing templates, building with Rynko's visual designer and structured JSON is faster than writing HTML/CSS from scratch and wiring up a Puppeteer pipeline.

• You need PDF and Excel. This is the clearest decision point. If both formats are required, Rynko eliminates the second pipeline.

• Performance matters. High-throughput generation, user-facing download buttons, serverless environments — anywhere the 3–8 second Puppeteer time is a problem.

• Non-developers need to edit templates. The visual designer lets product, finance, or operations teams make layout changes without a code deploy.

• You're building AI-powered workflows. The MCP server lets AI agents create templates and generate documents through conversation, with schema validation that prevents the broken-HTML problem.

• You want deterministic output. No Chrome version drift, no CSS rendering differences between environments, no surprises when your CI server renders differently from your local machine.

Migrating from Puppeteer

If you're currently using Puppeteer and want to try Rynko, the migration path doesn't have to be all-or-nothing.

The MCP server can help with the conversion. Point Claude Desktop or Cursor at your existing HTML template and ask it to recreate the layout as a Rynko template. The AI analyzes the HTML structure, identifies dynamic fields, and maps them to template variables and components. It won't produce a pixel-perfect replica every time, but it gets you 80–90% of the way there, and the visual designer lets you refine the rest.

You can also start by migrating a single template — try an invoice or a simple report — and run both pipelines in parallel while you evaluate. Rynko's free tier includes 50 documents per month, and every new account gets 5,000 credits during the Founder's Preview, so there's room to test with real workloads before committing.

Try Rynko Free | Documentation | MCP Setup

Questions or feedback: support@rynko.dev or Discord.

Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.

If you are building a SaaS, you eventually have to generate an invoice, a receipt, or a complex report. Developers usually waste days wrestling with CSS media queries or setting up resource-heavy HTML-to-PDF microservices using Puppeteer. Rynko provides the infrastructure to design, version, and generate documents deterministically. You can go from a blank canvas to a production-ready template in minutes and get back to building your core product.

Architecture: Native Speed, No Bloat

Rynko generates PDF and Excel documents from a single definition. This definition is a structured JSON component tree rather than HTML.

We explicitly chose not to use HTML because headless browsers are heavy. A standard Chromium-based PDF generator can easily consume hundreds of megabytes of RAM per instance. Rynko uses a native layout pipeline powered by the Yoga Layout Engine and PDFKit.

The result is a massive win for your server costs and performance:

• Low Footprint: Rynko workers operate at roughly 50MB of memory.

• High Speed: Documents generate in a median of 426 milliseconds.

• Deterministic: Identical JSON input produces identical PDF output every single time. There are no rendering differences between your local machine and your production server.

The Template Designer

You do not have to write the JSON manually. Templates are designed visually using a drag-and-drop editor that supports over 19 component types. These include data tables, charts, dynamic QR codes, and conditional logic.

Each component has a strict property schema validated at design time. You can preview templates in real time with live variable substitution and sample data. Once designed, the exact same template can generate both a highly styled PDF and a formatted Excel spreadsheet with native formulas.

AI Integration: Let Agents Do the Work

To make integration even faster, we built a native Model Context Protocol (MCP) server. This allows AI agents from Claude Desktop, Cursor, or Windsurf to interact with Rynko directly.

You can prompt your IDE to "Generate an invoice template for Acme Corp with a tax calculated field." The agent will use the MCP tools to build the JSON tree and draft the template. You can then review it visually in the dashboard before using it in your application.

Developer Experience

We treat document generation as a code-first citizen. We provide official SDKs for Node.js, Python, and Java. These SDKs feature automatic retries with exponential backoff.

You can batch generate multiple documents in a single API call. Final documents are delivered via cryptographically signed URLs that automatically expire after three days. Webhook deliveries include HMAC-SHA256 signature verification so you can securely update your database when a document is ready.

Infrastructure That Grows with You

Rynko is easy enough for a weekend side project, but it is built to handle enterprise scale when your startup grows.

We organize resources using Projects and Environments. You get complete resource isolation for your dev, staging, and production environments. When you land enterprise clients, Rynko is ready with PDF/A-2b compliance for long-term archival, role-based access control for your team, and full audit logs.

Join the Public Beta: Founder's Preview

Rynko isn't just a basic PDF wrapper. We are building the deterministic infrastructure that allows developers and AI agents to generate documents at scale.

Rynko is currently in Public Beta: Founder's Preview. Join today to claim 5,000 free document generation credits and start building deterministic document workflows without the Chromium overhead.

**
Try It Free** | MCP Setup Guide | Documentation

Questions? Join our Discord or check the npm package.

Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.

The Gap in AI Agent Capabilities

Picture this: you're using Claude to analyze your quarterly sales data. It queries your database, crunches the numbers, identifies trends, and writes a summary. Then you say:

"Great. Now turn that into a PDF report I can send to the board."

And suddenly, the most capable AI in the world is stuck. It can give you Markdown. It can generate HTML. But a real, formatted PDF with your company logo, charts, page numbers, and a professional layout? That requires infrastructure the AI agent simply doesn't have access to.

This is the gap we built Rynko's MCP server to fill.

What Is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and services. Think of it as a USB port for AI—a standardized way for models like Claude to interact with the outside world.

When you connect an MCP server to Claude Desktop or Cursor, the AI gains new abilities. It can read files, query APIs, execute code—anything the server provides.

Our MCP server enables AI agents to design templates, generate documents, and manage the entire document lifecycle—all through natural conversation.

What Our MCP Server Can Do

Here are the tools provided by the Rynko Document Generation MCP:

1. list_workspaces — List all workspaces you have access to, including workspace names, team names, and your role.

2. get_workspace — Get details about a specific workspace including template count and team information.

3. list_templates — List templates in a workspace, filterable by format (PDF or Excel).

4. get_template — Get full details of a template including schema, variables, and settings.

5. create_draft_template — Create a new draft template with a defined schema and variables.

6. update_draft_template — Update an existing template's draft version (name, description, schema, or variables).

7. validate_schema — Validate a template schema without creating a template; returns any validation errors.

8. get_schema_reference — Fetch the complete Rynko template schema reference documentation (all component types, examples, styling, validation rules, etc.).

9. parse_data_file — Parse an Excel or CSV file and return structured JSON data for document generation.

10. map_variables — Auto-map data columns to template variables based on name similarity, with confidence scores.

11. preview_template — Generate a free preview of a document with a download URL (valid 5 minutes). Doesn't consume credits.

12. generate_document — Generate a production document (consumes credits). Returns a job ID for status tracking.

13. get_job_status — Check the status of a document generation job and get the download URL when complete.

14. list_assets — List image assets in your asset library (returns assets://{id} references for use in templates).

15. upload_asset — Upload an image (base64 or public URL) to the asset library for use in templates.

16. get_sdk_examples — Get SDK code examples and documentation for programmatic integration (Node.js, Python, Java, REST).

These cover the full lifecycle — from workspace/template management, schema authoring and validation, data parsing and variable mapping, to preview, generation, asset management, and developer integration.

Template Creation and Management

Your AI agent can create document templates from a natural language description:

The agent will create a well-structured template with all the necessary components, variables, and layout using our template schema. Templates created through MCP begin as drafts, ensuring nothing goes to production without your review.

Document Generation

Once you have a template, generating documents is a single conversation turn:

"Generate a PDF invoice for Acme Corp using the invoice template.
Invoice #INV-2026-042, 3x Consulting Hours at $150/hr,
1x Software License at $500. 8% tax."

The agent fills in the variables, calls the generation API, and provides a download link. You can also create Excel files from the same template—just ask.

Previews are free. The agent can generate preview documents without using up your monthly quota, allowing you to refine templates without worrying about costs.

Data Import

Have data in a spreadsheet? The agent can parse it and map it to your template:

"Parse this CSV file and map the columns to the invoice template variables"

The parse_data_file and map_variables tools manage Excel and CSV files by automatically matching column headers to the template variable names.

Asset Management

Templates often need images, such as logos, signatures, and icons. The agent can upload and manage these assets:

"Upload our company logo for use in templates"

Assets are stored in your team's library and can be used in all templates.

Setup: Just 2 Minutes, No Coding Needed

Step 1: Acquire a Personal Access Token

1. Log into app.rynko.dev

2. Go to Settings > Personal Access Tokens

3. Create a new token (expires in 30 days for security)

Step 2: Integrate with Your AI Tool

Claude Desktop — download the .mcpb extension from our GitHub releases and drag it into Settings > Extensions. Enter your token when prompted. That's it.

Or, if you prefer manual config, edit claude_desktop_config.json:

{
  "mcpServers": {
    "rynko": {
      "command": "npx",
      "args": ["-y", "@rynko/mcp-server"],
      "env": {
        "RYNKO_USER_TOKEN": "pat_your_token_here"
      }
    }
  }
}

Cursor — Open Settings (Cmd+, / Ctrl+,) → Features → MCP → Add New MCP Server. Enter the name rynko, select the type command, input the command npx -y @rynko/mcp-server, and add the environment variable RYNKO_USER_TOKEN with your token. Save and restart.

Upon restarting Cursor, the document generation tools will be available immediately.

We also support Windsurf, VS Code, and Zed — see our MCP integration guide for setup instructions.

Why Choose MCP Over a Standard API?

You might wonder — why build an MCP server when we already have a REST API?

The answer is context and intent.

When a developer integrates our API, they write code that knows exactly what template to use, what variables to pass, and what format to generate. The logic is hardcoded.

When an AI agent uses our MCP server, it can reason about the problem. It can:

• Browse available templates and pick the right one based on name, description, and format

• Inspect a template's variables — see what fields exist, what types they expect, what defaults are set — and map incoming data to them (we even have a map_variables tool that does fuzzy column-to-variable matching)

• Generate a free preview first, check if the output looks right, and regenerate with tweaked data if needed

• Create an entirely new draft template from scratch if none of the existing ones fit

The difference is that the API caller needs to know exactly what to do upfront. The MCP caller can explore, inspect, and iterate — more like a junior developer with access to your template library than a script executing a fixed pipeline.

Real-World Workflows

Here are workflows where MCP actually makes sense — cases where a human is in the loop and the AI is doing the legwork interactively:

Ad-Hoc Invoice Generation

You're in a chat with Claude and a client just confirmed a project scope over email. You say: "Generate an invoice for Acme Corp — 3 months of consulting at $15k/month, net-30 terms." The agent lists your templates, picks your invoice template, inspects its variables, fills them in, generates a preview, and gives you a download link. You review it, ask for a tweak ("add a 10% early payment discount line"), and the agent regenerates. Two minutes, no context switching to a dashboard.

On-Demand Reporting

You ask Claude: "Generate this month's sales report." The agent queries your database (via a separate DB tool or MCP server you've configured), structures the data to match your report template's variables, and generates a PDF. This works well when the template already exists and the variables are straightforward — but you need the data source wired up separately. The MCP server handles the document generation part, not the data fetching.

Template Prototyping

You're building a new onboarding packet and don't want to spend 30 minutes in the visual designer for the first draft. You describe what you need: "Create a welcome letter template with company name, employee name, start date, and a list of first-week tasks." The agent uses create_draft_template to build a structured template, generates a preview with sample data, and you iterate from there. Once you're happy with the structure, you open it in the visual designer to polish the layout and publish.

Secure by Design

We prioritized security when building the MCP server:

• Personal Access Tokens expire after 30 days and are stored as SHA-256 hashes

• Draft-only mode — templates created via MCP are always drafts until manually published

• Workspace isolation — the MCP server enforces workspace selection at session start. The AI must list your workspaces, let you pick one, and lock to it before any template or document operations work. Switching workspaces requires explicit re-selection.

• Audit trail — every MCP operation is logged in your team's activity feed

• Token revocation — instantly revoke any token from the dashboard

Getting Started

1. Sign up for free — You'll get 5,000 credits with every new account!

2. Install the MCP server — It only takes 2 minutes to set up for Claude, Cursor, or any MCP client.

3. Ask your agent: "List my Rynko templates" — If it works, you're all set and connected!

We created this because we believe the future of document generation should be as easy as having a conversation. Instead of learning another API, you just tell your AI what you need.

Try It Free | MCP Setup Guide | Documentation

Questions? Join our Discord or check the npm package.

_{Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.}

Most document generation tools make you choose: build a PDF template or an Excel template. Need both formats? Build two templates, maintain two schemas, handle two sets of bugs.

We thought that was unnecessary. So, we built a unified template system where you design once and generate in any format. This post explains how it works under the hood.

The Problem with Separate Templates

Consider a typical invoice. Your sales team wants PDF invoices for customers. Your finance team wants the same data as Excel for their accounting software. Your ops team wants Excel reports they can sort and filter.

With traditional tools, you'd maintain:

• An HTML template for the PDF invoice

• A separate Excel template (or code that builds spreadsheets)

• Logic to keep both templates in sync when the invoice format changes

When someone adds a "discount" field, you update the PDF template, then remember to update the Excel template too. Inevitably, they drift apart.

The Rynko Approach

In Rynko, a template is a JSON document that describes the structure and data of your document, not the final visual output. The renderers — one for PDF, one for Excel — interpret that structure for their respective formats.

Here's a simplified view of an invoice template:

{
  "name": "Invoice",
  "format": "both",
  "variables": [
    { "name": "invoiceNumber", "type": "string" },
    { "name": "customerName", "type": "string" },
    { "name": "items", "type": "array", "itemType": "object",
      "schema": {
        "itemSchema": {
          "properties": {
            "description": { "type": "string" },
            "quantity": { "type": "number" },
            "price": { "type": "number" }
          }
        }
      }
    },
    { "name": "total", "type": "number" }
  ],
  "sections": [
    {
      "components": [
        { "type": "heading", "props": { "text": "Invoice #{{invoiceNumber}}" } },
        { "type": "text", "props": { "text": "Bill to: {{customerName}}" } },
        {
          "type": "dataTable",
          "props": {
            "dataSource": "{{items}}",
            "columns": [
              { "header": "Description", "field": "description" },
              { "header": "Qty", "field": "quantity" },
              { "header": "Price", "field": "price", "format": "currency" }
            ]
          }
        },
        { "type": "text", "props": { "text": "Total: ${{total}}", "bold": true } }
      ]
    }
  ]
}

This single template produces both a formatted PDF and a structured Excel workbook. The same variable data feeds both.

How the Rendering Works

The Layout Engine: Yoga

At the core of our PDF and Designer pipeline is Yoga — the same flexbox layout engine that powers React Native. Every component in a template becomes a Yoga node with flex properties:

Template Section
├── Heading node (flex: row, alignItems: center)
├── Text node (marginBottom: 10)
├── DataTable node
│   ├── Header row (flex: row, backgroundColor: #f5f5f5)
│   └── Data rows (flex: row, borderBottom: 1px)
└── Total text node (flex: row, justifyContent: flex-end)

Yoga calculates the exact position and size of every element. This gives us pixel-perfect PDF layout and live preview in the designer — without parsing HTML or running a browser.

For Excel, we bypass the pixel layout engine entirely and map the component tree directly to spreadsheet rows and columns. Yoga deals in X/Y coordinates; Excel deals in rows and cells — so each renderer interprets the same component tree in the way that's native to its format.

PDF Renderer

The PDF renderer takes the Yoga layout tree and draws directly to PDFKit:

1. Layout pass: Yoga calculates positions for all nodes

2. Render pass: Each component type has a renderer that draws to PDFKit

   • heading → doc.fontSize(24).text(...)

   • dataTable → Table drawn with lines, cells, formatting

   • image → doc.image(...) with proper scaling

   • chart → Rendered to canvas, then embedded as image

3. Pagination: When content exceeds page height, automatic page breaks with header/footer repetition

4. Output: Native PDF file, no browser involved

Result: 200-500ms generation, ~50MB memory.

Excel Renderer

The Excel renderer interprets the same template for spreadsheet format:

1. Sheet mapping: Each template section can map to an Excel sheet

2. Component translation:

   • heading → Merged cells with bold formatting

   • text → Cell with text and formatting

   • dataTable → Excel table with headers, data rows, and auto-filters

   • chart → Native Excel chart object

   • image → Embedded image in cell

3. Formula support: Define native Excel formulas in your template for cells that should calculate in the spreadsheet

4. Formatting: Fonts, colors, borders, number formats translate to Excel styles

Result: A proper .xlsx file with native Excel features — not a CSV, not a screenshot of a table.

Component-by-Component Translation

All 28 component types and how they map across formats:

Content Components

Layout Components

Data & Visualization Components

PDF Form Components (PDF only)

What's Format-Specific

Some features only make sense in one format:

PDF only:

• 8 fillable form field types (text, textarea, checkbox, radio, dropdown, date, signature, button)

• Custom fonts

• Precise Yoga flexbox positioning

• Page headers and footers

Excel only:

• Native Excel formulas via Formula component

• Auto-filters on data tables

• Sortable columns

• Cell-level data types (dates as dates, numbers as numbers)

The Variable System

Variables are format-agnostic. You define them once, and both renderers use the same data:

Scalar Variables

{ "name": "customerName", "type": "string", "defaultValue": "John Doe" }

Works identically in both formats — the value appears wherever {{customerName}} is used.

Array Variables (Dynamic Tables)

{
  "name": "items",
  "type": "array",
  "itemType": "object",
  "schema": {
    "itemSchema": {
      "properties": {
        "description": { "type": "string" },
        "quantity": { "type": "number" },
        "price": { "type": "number" }
      }
    }
  }
}

• PDF: Renders as a table with one row per array item, automatically paginating

• Excel: Creates data rows with proper column types and formatting

Calculated Variables

{ "name": "subtotal", "type": "number", "expression": "items.reduce((sum, item) => sum + item.quantity * item.price, 0)" }

• PDF: Evaluated server-side, result rendered as text

• Excel: Evaluated server-side, result placed in the cell as a static value. If you need live Excel formulas (e.g., =SUM(D2:D10)), define them separately in the template's Excel formula configuration

System Variables

Both formats support system-provided variables like __CURRENT_DATE__, __COMPANY_NAME__, __TEMPLATE_NAME__, etc. These are resolved identically regardless of output format.

Why This Architecture?

We considered several approaches before settling on the Yoga-based unified template:

Rejected: HTML as the Source

We could have used HTML templates and converted to both PDF and Excel. But:

• HTML-to-Excel conversion is lossy — you can't preserve semantic data

• Tables in HTML become images or flat text in Excel, losing sort/filter capability

• Browser-based rendering is slow and resource-heavy

Rejected: Separate Templates with Shared Schema

We could have had separate PDF and Excel templates that share the same variables. But:

• Two templates to maintain = two places for bugs

• Templates inevitably drift apart

• More work for template designers

Chosen: Abstract Component Tree

By defining templates as an abstract component tree (not HTML, not Excel XML), each renderer can interpret components optimally for its format:

• The PDF renderer uses Yoga for precise layout

• The Excel renderer uses native Excel features (real tables, real formulas)

• Both consume the same template and variables

Try It Yourself

You can see this in action in under 5 minutes:

1. Sign up free at Rynko

2. Create a template in the visual designer

3. Click "Preview" and toggle between PDF and Excel output

4. Send the same data via API and get both formats

Here's the dual-format payoff in code — same template, same variables, two API calls:

import { Rynko } from '@rynko/sdk';

const rynko = new Rynko({ apiKey: process.env.RYNKO_API_KEY! });

const invoiceData = {
  templateId: 'invoice',
  variables: {
    invoiceNumber: 'INV-2026-001',
    customerName: 'Acme Corp',
    items: [
      { description: 'Consulting', quantity: 10, price: 150.00 },
      { description: 'Software License', quantity: 5, price: 99.00 },
    ],
    total: 1995.00,
  },
};

// PDF for the customer
const pdf = await rynko.documents.generatePdf(invoiceData);

// Excel for the finance team — same template, same data
const excel = await rynko.documents.generateExcel(invoiceData);

Or, if you're using Claude or Cursor, ask the AI to create a template and generate both formats:

Create an invoice template, then generate it as both PDF and Excel
with sample data for 3 line items

The same JSON data, the same template, two perfectly formatted documents.

New to Rynko? Follow our Getting Started in 5 Minutes guide. Evaluating alternatives? See the PDF Generation API Comparison.

Get Started Free | Template Schema Reference | Rendering Engine

Questions about the rendering architecture? Join our Discord or check the engine page for the full breakdown.

_{Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.}

This guide walks you through generating your first document with Rynko. By the end, you'll have a working PDF generated from a template via our API.

Step 1: Create Your Account (30 seconds)

Head to app.rynko.dev/signup and create a free account. No credit card required.

Every new account comes with 5,000 free document credits as part of our Founder's Preview — more than enough to build and test.

Step 2: Create a Template (2 minutes)

Once you're in the dashboard, click New Template to open the visual designer.

You have three options:

Option A: Use a Pre-Built Template

Browse the template gallery and pick one that's close to what you need — invoices, reports, certificates, and more. Customize it in the designer.

Option B: Design from Scratch

The drag-and-drop designer supports 28 component types. Drag in text, tables, images, charts, QR codes, and more. Set up variables using {{variableName}} syntax in any text field.

Option C: Let AI Create It (MCP)

If you're using Claude Desktop or Cursor with our MCP server, just describe what you need:

"Create an invoice template with company logo, customer details,
a line items table, and totals with tax calculation"

For this guide, let's create a simple invoice. Add these variables to your template:

Click Publish when you're happy with the design.

Tip: Use the Preview button to test your template before publishing. Previews are free and don't consume credits.

Step 3: Get Your API Key (30 seconds)

Go to Settings > API Keys and create a new key. Copy it — you'll need it in the next step.

Your API key starts with your team ID and gives programmatic access to your templates and document generation.

Step 4: Generate a Document (2 minutes)

Pick your language:

You can also test document generation without code using the API Playground in your dashboard — paste in variables and generate a document directly from the browser.

Node.js

npm install @rynko/sdk

import { Rynko } from '@rynko/sdk';

const rynko = new Rynko({
  apiKey: process.env.RYNKO_API_KEY!,
});

// Generate a PDF
const job = await rynko.documents.generatePdf({
  templateId: 'invoice', // Your template slug, shortId, or UUID
  variables: {
    invoiceNumber: 'INV-2026-001',
    clientName: 'Acme Technologies Pvt. Ltd.',
    clientEmail: 'accounts@acmetech.com',
    lineItems: [
      { description: 'Technical Consulting', quantity: 2, price: 150.00 },
      { description: 'Software License', quantity: 1, price: 500.00 },
    ],
    subtotal: 800.00,
    tax: 80.00,
    total: 880.00,
  },
});

console.log('Job queued:', job.jobId);

// Wait for completion
const completed = await rynko.documents.waitForCompletion(job.jobId);
console.log('Download URL:', completed.downloadUrl);

Python

pip install rynko

import os
from rynko import Rynko

client = Rynko(api_key=os.environ["RYNKO_API_KEY"])

# Generate a PDF
job = client.documents.generate_pdf(
    template_id="invoice",
    variables={
        "invoiceNumber": "INV-2026-001",
        "clientName": "Acme Technologies Pvt. Ltd.",
        "clientEmail": "accounts@acmetech.com",
        "lineItems": [
            {"description": "Technical Consulting", "quantity": 2, "price": 150.00},
            {"description": "Software License", "quantity": 1, "price": 500.00},
        ],
        "subtotal": 800.00,
        "tax": 80.00,
        "total": 880.00,
    },
)

print(f"Job queued: {job['jobId']}")

# Wait for completion
completed = client.documents.wait_for_completion(job["jobId"])
print(f"Download URL: {completed['downloadUrl']}")

cURL

# Generate a document
curl -X POST https://api.rynko.dev/api/v1/documents/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "invoice",
    "format": "pdf",
    "variables": {
      "invoiceNumber": "INV-2026-001",
      "clientName": "Acme Technologies Pvt. Ltd.",
      "clientEmail": "accounts@acmetech.com",
      "lineItems": [
        {"description": "Technical Consulting", "quantity": 2, "price": 150.00},
        {"description": "Software License", "quantity": 1, "price": 500.00}
      ],
      "subtotal": 800.00,
      "tax": 80.00,
      "total": 880.00
    }
  }'

# Response includes a jobId - poll for completion
curl https://api.rynko.dev/api/v1/documents/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Run the code. In under a second, you'll get a signed download URL for your PDF. Click it — there's your document.

Want Excel Instead?

Same template, different format:

// Node.js
const job = await rynko.documents.generateExcel({
  templateId: 'invoice',
  variables: { /* same variables */ },
});

# Python
job = client.documents.generate_excel(
    template_id="invoice",
    variables={ ... },
)

That's it. One template, both formats.

Step 5: Set Up Webhooks (Optional)

Instead of polling for completion, you can receive a webhook when your document is ready:

1. Go to Settings > Webhooks in the dashboard

2. Add your endpoint URL

3. Select the document.generated event

When a document finishes generating, we'll POST to your endpoint with the download URL:

import { verifyWebhookSignature } from '@rynko/sdk';

app.post('/webhooks/rynko', (req, res) => {
  const event = verifyWebhookSignature({
    payload: req.body.toString(),
    signature: req.headers['x-rynko-signature'],
    secret: process.env.WEBHOOK_SECRET,
  });

  if (event.type === 'document.generated') {
    console.log('Document ready:', event.data.downloadUrl);
  }

  res.status(200).json({ received: true });
});

What's Next?

Now that you've generated your first document, here's what to explore:

• Visual Designer — Design templates with drag-and-drop, live preview, and 28 component types

• MCP Server — Let Claude or Cursor create and generate documents for you

• API Reference — Full API documentation with interactive examples

• Template Schema — Deep dive into template structure and capabilities

• Integrations — Connect with Zapier, Make.com, n8n, and Google Sheets

Need Help?

• Documentation — Guides, tutorials, and API reference

• Discord — Chat with the team and community

• support@rynko.dev — Email support

Happy generating!

_{Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.}

Claude Desktop is already great at analyzing data, writing content, and answering questions. But what if it could also generate real, formatted PDF documents?

With Rynko's MCP server, it can. This tutorial shows you how to set it up and start generating documents from Claude Desktop in under 5 minutes.

What You'll Build

By the end of this tutorial, you'll be able to:

• Ask Claude to create document templates from a description

• Generate PDF invoices, reports, and certificates from conversation

• Preview documents before using credits

• Generate Excel files from the same templates

Prerequisites

• Claude Desktop installed

• A free Rynko account (5,000 credits included)

Step 1: Get a Personal Access Token

MCP connections use Personal Access Tokens (PATs) instead of API keys. Here's how to create one:

1. Log into app.rynko.dev

2. Go to Settings > Personal Access Tokens

3. Click Create Token

4. Give it a label like "Claude Desktop"

5. Set the expiry (up to 30 days)

6. Copy the token — it starts with pat_ and won't be shown again

Step 2: Install the Rynko Extension

There are two ways to install — pick whichever you prefer.

Option A: One-Click Install (Recommended)

The fastest way. Download the .mcpb extension package and drag it into Claude Desktop:

1. Download rynko-mcp-{version}.mcpb from the latest release

2. In Claude Desktop, go to Settings > Extensions

3. Drag the downloaded .mcpb file into the install area (or click Install from file)

4. Click Configure on the Rynko extension and enter your Personal Access Token

That's it — no config files, no terminal commands.

Option B: Manual Configuration

If you prefer editing config files directly, open your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add the Rynko MCP server:

{
  "mcpServers": {
    "rynko": {
      "command": "npx",
      "args": ["-y", "@rynko/mcp-server"],
      "env": {
        "RYNKO_USER_TOKEN": "pat_your_token_here"
      }
    }
  }
}

Save the file and restart Claude Desktop.

Step 3: Verify the Connection

Start a new conversation in Claude Desktop and type:

List my Rynko workspaces

Claude should respond with your workspace names and IDs. If it does, you're connected. If not, double-check your config file for JSON syntax errors and make sure the token is valid.

Generating Your First Document

Create a Template

Let's start by asking Claude to create an invoice template:

Create a Rynko invoice template with:
- Company header with logo placeholder and company name
- "Bill To" section with customer name, address, and email
- Invoice number and date fields
- A line items table with columns: Description, Quantity, Unit Price, Amount
- Subtotal, tax rate, tax amount, and total
- Payment terms at the bottom

Claude will use the create_draft_template tool to build a properly structured template. It handles the layout, component types, and variable definitions automatically.

Pro Tip: You can drag and drop your company logo into the chat and say "Upload this as my logo." Claude will save it to your Rynko asset library and automatically link it in the template.

Preview the Template

Before generating a real document, preview it with sample data:

Preview the invoice template I just created with this data:
- Company: Rynko Inc
- Customer: Acme Corp, 456 Business Ave, San Francisco CA
- Invoice #INV-2026-001, dated today
- Items: 10 hours of consulting at $150/hr, 1 software license at $500
- Tax rate: 8%

Claude will generate a preview PDF and give you a download link. Previews are free (and watermarked) — they don't count against your quota.

Generate a Production Document

Happy with the preview? Generate the real thing:

Generate a PDF invoice with these details:
- Customer: TechStart LLC, 789 Innovation Dr, Austin TX
- Invoice #INV-2026-002
- 5x API Integration Setup at $200 each
- 2x Monthly Support at $99 each
- Tax: 8.25%
- Payment terms: Net 30

Claude calculates the totals, fills in all the variables, and asks you to confirm the credit usage: "This will use 1 document from your monthly quota. Proceed?" Once you say yes, it generates the PDF and gives you a download link in seconds.

Generate Excel Instead

Want the same data as an Excel file?

Generate that same invoice as an Excel file instead of PDF

Same template, same data, different format. The Excel file includes proper cell formatting, formulas, and structure.

Recreate Any Document from a Sample

Here's one of the most powerful things you can do: upload an existing document and have Claude recreate it as a Rynko template.

Claude Desktop supports file uploads — PDFs, images, screenshots. Since Claude is multimodal, it can visually analyze a document's layout, structure, fonts, spacing, and data fields. Combine that with Rynko's MCP tools, and you get this workflow:

1. Upload a sample invoice, report, or certificate (PDF or screenshot)

2. Ask Claude to recreate it

I've uploaded a sample invoice we currently use. Create a Rynko
template that matches this layout as closely as possible. Identify
all the dynamic fields and create variables for them.

Claude will:

• Analyze the visual layout — header position, table structure, column widths, alignment

• Identify which parts are static (labels, logos) and which are dynamic (names, amounts, dates)

• Create a Rynko template with the right components and variables

• Match the general styling — fonts, colors, spacing

This means you can migrate existing documents to Rynko without manually recreating every template from scratch. Upload your current invoice PDF, and Claude builds the template for you.

Works great for:

• Migrating from Word/mail merge templates

• Recreating documents you only have as PDFs (no source file)

• Converting a designer's mockup into a working template

• Matching a client's existing document format

After Claude creates the draft, preview it with sample data, compare with the original, and ask for adjustments until it matches.

Advanced: Multi-Document Workflows

Once you're comfortable with the basics, try more complex workflows:

Batch Invoice Generation

I have these 3 invoices to generate:

1. Acme Corp - INV-001: 5x Widget A at $50, 2x Widget B at $75
2. TechStart - INV-002: 10 hours consulting at $150/hr
3. GlobalCo - INV-003: 1x Enterprise License at $5,000

Generate all 3 as PDFs using the invoice template. Tax rate 8% for all.

Claude will generate each one and give you all three download links.

Data Analysis + Report Generation

Here's our Q1 sales data: [paste your data]

Analyze the trends, identify the top performing regions,
then generate a PDF report with a summary, charts, and
a detailed breakdown table.

Claude analyzes the data, creates a report template if needed, and generates a formatted PDF with charts and tables.

Template Inspection

Not sure what variables a template needs?

Show me the variables for the invoice template

Claude will list every variable with its type, whether it's required, and its default value.

Tips for Best Results

1. Be specific about layout — "header with logo on the left and company info on the right" works better than "add a header"

2. Specify variable types — "items should be an array of objects with description (string), quantity (number), and price (number)" helps Claude create the right schema

3. Preview first — Always preview before generating production documents. Previews are free and let you catch issues early

4. Use existing templates — Ask Claude to list your templates before creating new ones. You might already have what you need

5. Iterate on drafts — Templates created via MCP are always drafts. Ask Claude to update them until they're right, then publish from the dashboard

Troubleshooting

What's Next?

• Customize templates in the visual designer for pixel-perfect control

• Set up webhooks to get notified when documents are ready

• Explore the API for programmatic integration

• Try Cursor — our MCP server works there too

Need help? Join our Discord or email support@rynko.dev.

_{Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.}

If you're building an app that needs to generate documents — invoices, reports, contracts — you probably have a dedicated document service or a messy Puppeteer setup. What if you could design templates, test generation, and integrate the API all from within Cursor?

With Rynko's MCP server, Cursor can create document templates, generate PDFs and Excel files, and help you write the integration code — all in a single workflow.

Why This Matters for Developers

When you're building a feature that generates PDFs, the workflow usually looks like:

1. Open the document service dashboard in a browser tab

2. Design a template there

3. Switch back to your editor

4. Write the API integration code

5. Test, realize the template needs changes

6. Switch back to the browser, tweak the template

7. Repeat

With MCP, Cursor becomes your document generation command center. Template creation, testing, and code generation happen in the same place you're writing your application code.

Setup (2 Minutes)

Prerequisites

• Cursor installed

• A free Rynko account

• A Personal Access Token (create one at Settings > Personal Access Tokens in the dashboard)

Configure MCP

The easiest way is through Cursor's settings UI:

1. Open Cursor Settings (Cmd+, / Ctrl+,)

2. Go to Features > MCP

3. Click Add New MCP Server

4. Enter a name (e.g., "rynko") and select command as the type

5. Enter the command: npx -y @rynko/mcp-server

6. Add the environment variable: RYNKO_USER_TOKEN = pat_your_token_here

7. Click Save

Alternatively, you can add it directly to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global access):

{
  "mcpServers": {
    "rynko": {
      "command": "npx",
      "args": ["-y", "@rynko/mcp-server"],
      "env": {
        "RYNKO_USER_TOKEN": "pat_your_token_here"
      }
    }
  }
}

Restart Cursor. The Rynko tools will appear in Cursor's MCP tool list.

Verify It Works

Open Cursor's AI chat (Cmd+L / Ctrl+L) and type:

List my Rynko workspaces and templates

If you see your workspace and any existing templates, you're ready.

Workflow 1: Build a Document Feature from Scratch

Let's say you're building a SaaS app and need to add invoice generation. Here's the full workflow in Cursor:

Step 1: Create the Template

Create a Rynko PDF template called "customer-invoice" with:
- Company logo and name in the header
- Invoice number, date, and due date
- Customer name, email, and address
- Line items table: description, quantity, unit price, amount
- Subtotal, discount (optional), tax, total
- Payment instructions footer
- Professional styling with a blue accent color

Cursor creates the template via MCP. It's saved as a draft in your Rynko workspace.

Pro Tip: Have a company logo? Drop the image file into your project directory and tell Cursor: "Upload src/assets/logo.png as my company logo." Cursor will save it to your Rynko asset library and link it in the template.

Step 2: Test with Sample Data

Preview the customer-invoice template with:
- Invoice #INV-2026-100
- Customer: Acme Corp, john@acme.com
- Items: 3x "Monthly Subscription" at $99, 1x "Setup Fee" at $250
- 10% discount, 8% tax

Cursor generates a preview (free and watermarked) and gives you the download link. Check the PDF — if it needs tweaks, just describe what to change.

Step 3: Generate the Integration Code

Now here's where it gets powerful. Ask Cursor to write the code:

Write a TypeScript service that generates invoices using the
customer-invoice template via the Rynko SDK. Include:
- A generateInvoice function that accepts order data
- Webhook handler for document.generated events
- Error handling and retry logic
- Types for the invoice variables

Cursor writes the code knowing exactly what variables the template expects, because it just created the template. No guessing, no mismatched field names.

// Generated by Cursor with knowledge of the actual template schema
import { Rynko } from '@rynko/sdk';

interface InvoiceItem {
  description: string;
  quantity: number;
  unitPrice: number;
  amount: number;
}

interface InvoiceData {
  invoiceNumber: string;
  date: string;
  dueDate: string;
  customerName: string;
  customerEmail: string;
  customerAddress: string;
  items: InvoiceItem[];
  subtotal: number;
  discount?: number;
  tax: number;
  total: number;
}

const rynko = new Rynko({ apiKey: process.env.RYNKO_API_KEY! });

export async function generateInvoice(data: InvoiceData): Promise<string> {
  const job = await rynko.documents.generatePdf({
    templateId: 'customer-invoice',
    variables: data,
  });

  const completed = await rynko.documents.waitForCompletion(job.jobId);

  if (completed.status !== 'completed') {
    throw new Error(`Invoice generation failed: ${completed.errorMessage}`);
  }

  return completed.downloadUrl;
}

Step 4: Iterate

Need to change the template? Just ask in the same conversation:

Update the customer-invoice template to add a QR code
in the bottom right with the payment URL

Cursor updates the template and you can immediately test it again — without leaving the editor.

Workflow 2: Recreate Any Document from a Sample

Have an existing PDF, screenshot, or mockup? Cursor can recreate it as a Rynko template.

Drop the sample file into your project directory and ask:

Look at docs/sample-invoice.pdf. Create a Rynko template that
matches this layout. Identify all the dynamic fields and create
variables for them.

Cursor reads the file, analyzes the layout — header position, table structure, column widths, alignment, colors — and creates a matching template via MCP. It figures out which parts are static (labels, logos) and which are dynamic (names, amounts, dates).

Works great for:

• Migrating from Word/mail merge templates

• Recreating documents you only have as PDFs (no source file)

• Converting a designer's mockup into a working template

• Matching a client's existing document format

Workflow 3: Migrate HTML Templates to Rynko

Already have HTML templates or Puppeteer-based generation? Cursor can migrate both the template and the code:

I have this HTML invoice template in src/templates/invoice.html.
Create an equivalent Rynko template that matches the layout,
then write the migration code to replace the Puppeteer generation
with Rynko SDK calls.

Cursor reads your existing HTML, creates a matching Rynko template, and rewrites your generation code. You go from a 3-8 second Puppeteer pipeline to sub-500ms native rendering.

Workflow 4: Data-Driven Reports

Combine Cursor's code understanding with document generation:

Look at the analytics data shape in src/services/analytics.ts.
Create a Rynko report template that visualizes this data with:
- A summary section with key metrics
- A bar chart of monthly revenue
- A table of top customers
- Page break, then a detailed transaction log

Then write a scheduled job that generates this report weekly.

Cursor understands your data types, creates a matching template, and writes the automation code — all in one conversation.

Tips for Cursor + Rynko

1. Share config across the team — If using the .cursor/mcp.json file approach, commit it to your repo so every team member gets the same MCP setup (just use different tokens)

2. Let Cursor inspect templates — Before writing integration code, ask Cursor to get the template details. It'll write more accurate code when it knows the exact schema

3. Preview before publishing — Templates created via MCP are drafts. Preview them with sample data, iterate, then publish from the dashboard when ready

4. Keep templates in sync — If you update a template in the visual designer, ask Cursor to re-inspect it so it knows about the changes

5. Combine with your codebase — Cursor can read your existing types and models, then create templates that match your data shape perfectly

Available MCP Tools

Here's what Cursor can do via the Rynko MCP server:

Get Started

1. Sign up free — 5,000 credits included

2. Add the config to .cursor/mcp.json

3. Start a chat: "Create a Rynko template for..."

The best part: Cursor already understands your codebase. Combined with Rynko's MCP tools, it can build end-to-end document generation features that perfectly match your data models.

Get Started Free | MCP Documentation | SDK Reference

Our MCP server also works with Claude Desktop (one-click install via .mcpb extension), VS Code, Windsurf, and Zed. See the full setup guide.

_{Disclosure: I ideate and draft content, then refine it with the aid of artificial intelligence tools like Claude and revise it to reflect my intended message.}