# Form-to-JSON Extraction Agent

> A form-extraction agent that turns documents into schema-valid JSON, scores confidence per field, and flags illegible or missing fields instead of guessing.

- **Category:** Document Processing
- **Difficulty:** Advanced
- **Setup time:** 40 min
- **Stacks:** Claude, LangGraph, OpenAI
- **Version:** 2.0.0 (updated 2026-06-21)
- **Source:** https://agent-kits.com/kit/form-to-json-extractor

## Overview

Turns filled-in forms and documents into schema-valid JSON mapped to your fields.

Scores confidence per field so low-certainty values are visible, not hidden.

Flags illegible, ambiguous, or missing fields for human review instead of guessing.

Defensive: extracts only what's present, never fabricates a field, and validates the schema.

## When to use it

- You process forms or documents into structured data at volume.
- You want per-field confidence and a clean schema-valid output.
- You want illegible or missing fields flagged for review, not guessed.
- You need faithful extraction you can trust downstream.

## When not to use it

- You want it to fill in missing fields by inference — it won't guess values.
- You have no schema for it to map to and validate against.
- You can't review flagged low-confidence fields.
- Your documents are free-form with no extractable fields.

## Architecture

- **Document intake** — Receives the form/document and the target schema to extract into.
- **Field locator** — Locates each schema field's value on the document, including OCR for scanned input.
- **Faithful extractor** — Extracts each value as written without correcting, normalizing away, or merging fields.
- **Confidence scorer** — Attaches a confidence to every field based on clarity and OCR quality.
- **No-guess guard** — Blocks any invented or inferred value; absent or unreadable fields become null with a flag.
- **Schema validator** — Validates the output against the schema's types, required fields, and enums.
- **Review queue** — Routes low-confidence, illegible, ambiguous, and missing fields to a human.

## Files in this bundle

- `system-prompt.md` — the agent's system prompt
- `tools.json` — tool/function definitions the agent expects
- `workflow.md` — step-by-step run loop
- `.env.example` — environment variables to fill in
- `kit.json` — full structured metadata
- `starters/` — minimal starter snippets
- `LICENSE` — Apache-2.0 (code, configuration, and schema)
- `LICENSE-CONTENT` — CC BY 4.0 (specification text and documentation)
- `NOTICE` — attribution and trademark notice
- `run.py` — **runnable demo**: real agent loop with mock tools (`pip install anthropic`, set `ANTHROPIC_API_KEY`, `python run.py`)
- `agentaz.json` / `agentaz.schema.json` — AgentAz™ governance spec + schema

## Implementation notes

- Never guess or infer a field value; absent or unreadable fields must be null with a flag, because a confidently wrong value propagates silently into downstream systems.
- Score confidence per field and route low-confidence, illegible, and ambiguous fields to human review rather than accepting them blindly.
- Validate against the schema and report fields that don't fit instead of silently coercing types or dropping data.
- Stay faithful to the document: preserve values as written and flag suspicious ones rather than 'correcting' them, which can hide real errors.
- Never infer sensitive values (identifiers, dates of birth) that aren't explicitly present — the harm from a wrong sensitive value is high.
- Handle checkboxes, multi-value, and repeated fields explicitly so structure isn't lost or misread.
- Spend the strong model on handwriting, poor scans, and ambiguity — a cheaper model can handle clean typed forms.

## Variations

- **Basic — Field extractor:** Extracts document fields into schema-valid JSON with per-field confidence. On demand.
- **Advanced — Guarded extraction:** Adds no-guess guards, illegible/missing flagging, schema validation, and a human review queue for uncertain fields.
- **Enterprise — Document processing pipeline:** Adds batch ingestion, OCR tuning, multi-template schemas, human-in-the-loop review, and audit trails for high-volume IDP.

## FAQ

**Will it guess a field it can't read?**

No — that's its core constraint. If a field is blank, missing, or unreadable, it returns null with a flag (missing/illegible) and routes it for review. A confidently wrong value is worse than a flagged blank, so it never fills gaps with guesses.

**How do I know which values to trust?**

Every field carries a confidence score, and low-confidence, ambiguous, or poor-OCR fields are flagged for human review. You see exactly which values are solid and which need a look.

**Does it validate against my schema?**

Yes. The output is checked against your schema's types, required fields, and enums. Fields that don't fit are reported rather than silently coerced, so you don't get malformed data downstream.

**Will it 'fix' values it thinks are wrong?**

No. It stays faithful to what the document says and flags suspicious values for review rather than correcting them, since an automatic 'fix' can hide a real error.

**What about sensitive fields?**

It never infers sensitive values like ID numbers or dates of birth that aren't explicitly on the document, because a wrong sensitive value carries real risk. Missing ones are flagged for a human to supply.

**Can it handle scanned and handwritten forms?**

Yes, with OCR — but it assesses legibility and flags anything it can't read confidently, especially handwriting and poor scans, instead of guessing.


---

© 2026 AgentKits · www.agent-kits.com

**Open source.** Code, configuration, and the AgentAz™ schema are licensed under
**Apache-2.0**; specification text and documentation under **CC BY 4.0** (with
attribution to AgentKits, link to https://www.agent-kits.com). See LICENSE, LICENSE-CONTENT,
and NOTICE in this bundle. "AgentAz" and "AgentKits" are trademarks of AgentKits.

**Flagship reference blueprint.** View the source, AgentAz™ spec, and frozen v1.0 schema
in the public registry: https://github.com/agent-kits/agentaz
Original: https://agent-kits.com/kit/form-to-json-extractor
