Read the documents first, fill the form after.

What it does

The agent has two stages, and a save at the end.

1. Gets ready to read the documents. It loads the investor's KYC record and prepares a place to collect the outcome of each field it is about to try to fill in.
2. Reads documents and fills in fields. Based on which KYC form type the investor is using, the agent looks up the extraction rules configured for that form. Rules are grouped by document, so even if several form fields come from the same document the agent makes only one AI request per uploaded document, asking for everything it needs in one go. For each configured field:
   • If the document the rule expects has not been uploaded yet, the field is marked skipped — "Document not uploaded".
   • If overwrite mode is set to "only fill blank fields", which is the default, and the field already has something typed in, it is marked skipped — "Field already has a value". The investor's own typed entry is never overwritten by mistake.
   • Otherwise the document is sent to AI with a combined extraction prompt. On success each field's value is written onto the KYC record and marked extracted.
   • If the AI's response cannot be read, or anything else goes wrong, every field tied to that document is marked error.
3. Saves everything at once. All extracted values are written in a single save at the end. That save deliberately skips the form's normal validation rules, so a partially filled KYC can still be saved mid-wizard without erroring out on fields the investor has not reached yet.

This agent shows no step-by-step progress panel. It either runs immediately and finishes before the page reloads, when triggered from the Extract from Documents button, or runs in the background, when triggered from the document-first upload flow. Either way, what you see afterwards is a short summary message, or simply your form fields already filled in.

What it needs

This agent has no standard configuration checklist on its edit page the way most agents do. Its settings live in a configuration panel built specifically for it.

Extraction rules are not typed into a single text box. They are managed through an editable rule table in the agent's configuration panel, with one card per KYC form type and Add Rule and Remove Rule buttons. They are also seeded automatically the first time Setup All Agents is run for your entity, using your entity's actual Individual and Non-Individual KYC form types. The default starter rules are:

• Extract the tax ID number from the "Upload Tax ID" document.
• Extract the full permanent address from the "Upload Address Proof" document.

The default Individual KYC form type gets a third starter rule that pulls the investor's full name from the "Upload Tax ID" document. This auto-seeding happens once only, the first time, and only if no rules exist yet — it will never overwrite rules you have since customised.

Beyond configuration, the agent reads which KYC form type the investor is using, to decide which rule set applies; the investor's uploaded documents, matched to each rule by an exact trimmed name match against the document label the rule expects; and the investor's existing field values, to decide whether "only fill blank fields" mode should skip a given rule.

Setup checklist and warnings

Because this agent produces no report of its own, a broken setup used to be invisible — an investor's form simply stayed empty. The agent's General tab now shows a yellow warning banner when:

• No extraction rules are configured at all. The agent would run and extract nothing. Re-run Setup All Agents to seed the starter rules, or add rules in the configuration panel.
• Rules are tied to a KYC form type that no longer exists. This happens when form types were rebuilt after the rules were seeded. Those rules silently apply to nothing; re-run Setup All Agents, or re-create the rules against the current form types.

Check as well that each rule's document name exactly matches the upload label on the KYC form — "Upload Tax ID", for example. A near-miss name means that rule always reports "Document not uploaded".

Turning it on

• Where to switch it on. In the admin area, edit the entity and use the Support Agents section. This requires the Company Admin role.
• That same toggle also gates the document-first upload screen itself. The screen appears only when both this agent and a separate entity setting for the doc-first wizard are on, the KYC has not already been submitted, and no documents have been uploaded yet.
• An AI key is required. Every extraction is an AI request, so a key must be configured under AI → Support Agents → LLM Keys. Gemini Flash is the recommended model here, because it handles large scanned documents well.

Running it

There is no Run Now button and no manual batch option on the agent's own page, and it never runs on a schedule. It kicks in automatically at two points in the KYC document upload flow.

1. The document-first wizard. When an investor on the document-first wizard uploads their identity and address documents and clicks Continue to Fill Form, the documents are saved and the extraction job is queued to run in the background. The investor sees a brief processing screen that moves them on to the now pre-filled form once extraction finishes.
2. The Extract from Documents button. Shown directly on the KYC form, this runs the agent immediately against whatever documents are already uploaded, and returns the investor to the form with a summary showing how many fields were extracted, skipped, or hit an error.

Both paths always work against a single investor's KYC record; there is no entity-wide batch run. If no enabled KYC Doc Extractor Agent exists for the entity, the wizard simply skips extraction with no message, while the Extract from Documents button shows an alert saying the document extractor agent is not configured for this entity.

Where the output goes

There is no persisted, browsable report for this agent and no progress panel. Results are returned directly to whichever screen triggered it.

• From the Extract from Documents button — an immediate summary message: "Extracted N field(s) from your documents. X skipped (already filled or document not uploaded). Y error(s) — check server logs."
• From the document-first wizard — no summary at all beyond landing on the pre-filled form. The investor simply sees their fields already populated, or not, if extraction failed or was skipped.
• Field-by-field detail — visible only in server logs, which your CapHive technical contact can pull if you need to know exactly what happened with a specific document.

Reading the result

There is no Ready or Blocked status here, because this agent does not gate any other process. Each field it attempted ends in one of three states.

• Extracted — the value was read from the document and written into the field.
• Skipped — either the source document was not uploaded, or, in "only fill blank fields" mode, the field already had a value.
• Error — the AI request failed to produce a usable result. The underlying error message is captured for troubleshooting.

Where it can fail

• No KYC Doc Extractor Agent enabled for the entity. Both entry points check for an enabled agent first. If none is found, the wizard silently skips extraction — nothing queued, no message — while the button shows an explicit alert. If you have set this up before and it is still not working, check that the agent is enabled both as a record and via the entity-level toggle. Those are two separate switches.
• No extraction rules configured for this KYC's form type. The agent records a single skipped result, "No extraction rules configured for this form type", and does nothing further. This looks like the agent did nothing rather than an error you would notice. If your entity added a new KYC form type after the agent was first set up, re-run Setup All Agents to seed rules for it — auto-seeding only happens once, when no rules exist yet.
• A document name that does not exactly match what the rule expects. Matching is on the document's name against the rule's expected label, trimmed and case-sensitive. An upload named something close but not identical — "PAN card" instead of the expected "Upload Tax ID" — is silently skipped with "Document not uploaded", even though a document clearly was uploaded, just under another name.
• The AI's response cannot be parsed. Caught and recorded as an error for every field tied to that document, but the record is still saved for any other fields that succeeded. One bad document does not take down the whole extraction.
• Any other AI or network problem. Caught, recorded as an error per field, and logged. The agent moves on to the next document rather than stopping, so one problematic document does not block extraction from the others.
• "Always overwrite" mode on a record the investor has already partly filled in. Every matching rule re-extracts and replaces the existing value, including anything the investor corrected by hand after a previous extraction. This is intentional for deliberate re-extraction, but it can quietly wipe out manual corrections if switched on without realising the consequence.
• A misconfigured target field. If a rule's target field name does not match a real field on the KYC record, the value is still saved but tucked away somewhere the form does not display. A typo in the target field name — "full_anme" for "full_name" — raises no error; it just looks as though the field never got filled, because nothing on the form reads that misspelled key.
• No AI key configured while the agent is turned on. The extraction request simply fails. This is not treated as a special case: it shows up as the same generic error outcome as any other failure, so the investor or staff member sees "N error(s) — check server logs" with no indication that the cause is a missing key.
• Running the wizard and the manual button at the same time. Both try to fill in the same record. Click Extract from Documents while a wizard extraction is still running in the background for the same investor and both will try to save — whichever finishes last wins, with no conflict warning.
• Running against a KYC with no documents uploaded at all. Every rule resolves to skipped and the record is never even saved, since there is nothing new to save, so the investor proceeds to a completely blank form. That is expected for a KYC with no documents yet, not a malfunction.

Questions we get asked