Extract Data With an Agent | Documentation

This page covers schema-first extraction using GroundX Agent Harness: an agent drafts the YAML schema, creates the workflow, and helps you iterate. The underlying GroundX operations are the same ones documented in Extract Data from Documents.

Agent Harness is the promoted path for agent-driven extraction work, not a replacement for the direct SDK/API path. If you’re integrating extraction into your own application code rather than working through an agent, use Extract Data from Documents directly — this page adds an agent on top of the same workflow.

Start With The JSON You Want

Before writing anything, decide what JSON your application should get back. A utility statement, for example, might come back as:

1 {
2   "statement": {
3     "account_number": "123456789",
4     "due_date": "2026-06-30",
5     "total_amount_due": 128.55
6   },
7   "service": {
8     "service_address": "100 Main St, Denver, CO 80202"
9   }
10 }

Tell the agent what fields you need and where they should live in the response. The agent turns that into a schema — you don’t need to think in the schema format yourself.

Ask the agent: "I need to extract the account number, due date, and total
amount due from utility statements, plus the service address, as JSON."

Create One YAML File

The agent drafts a single YAML file that names the top-level JSON objects (statement, service) and the values under each one (account_number, due_date, total_amount_due, service_address). Each value gets a short description, identifying labels, and instructions for reading it off the document — GroundX uses this to find and extract the value.

The names you choose in the YAML are the names that come back in the JSON. To change the response shape, change the YAML names, not the document.

This is the same YAML format used in Extract Data from Documents — see that page for a full example file and field-level options.

Create Or Update The Workflow

Once the YAML looks right, the agent creates a GroundX workflow from it:

1 from groundx import GroundX
2 
3 client = GroundX(api_key="YOUR_API_KEY")
4 
5 workflow_response = client.create_extraction_workflow(
6     path="statement.yaml",
7     name="statement extraction",
8 )
9 
10 workflow_id = workflow_response.workflow.workflow_id

After changing the YAML, update the existing workflow instead of creating a new one:

1 client.update_extraction_workflow(
2     "workflow-id",
3     path="statement.yaml",
4     name="statement extraction",
5 )

Workflow updates send the full extraction settings, not a name-only patch — pass the YAML again whenever you want the custom settings to stay in effect. See Extract Data from Documents for the full set of create/update/load options.

Assign Before Ingest

This page assumes a bucket already exists — bucket_id below refers to that bucket’s ID. If you don’t have one yet, see Create Or Select A Bucket for how to create one.

A workflow only runs on documents uploaded after it’s assigned. Assign the workflow to the bucket, group, or account before you ingest anything — otherwise get_extract has nothing to return.

1 client.workflows.add_to_id(id=bucket_id, workflow_id=workflow_id)

Use client.workflows.add_to_account(...) instead when the workflow should be the default for every bucket on the account.

Ingest And Poll

Upload a document to the assigned bucket with process_level="full" so GroundX runs the workflow during ingest:

1 import time
2 
3 from groundx import Document, GroundX
4 
5 client = GroundX(api_key="YOUR_API_KEY")
6 
7 ingest_response = client.ingest(
8     documents=[
9         Document(
10             bucket_id=bucket_id,
11             file_name="statement.pdf",
12             file_type="pdf",
13             file_path="https://example.com/statement.pdf",
14             process_level="full",
15         )
16     ],
17 )
18 
19 process_id = ingest_response.ingest.process_id
20 
21 while True:
22     ingest_response = client.documents.get_processing_status_by_id(
23         process_id=process_id,
24     )
25     status = ingest_response.ingest.status
26 
27     if status in {"complete", "error", "cancelled"}:
28         break
29 
30     time.sleep(3)
31 
32 if status != "complete":
33     raise RuntimeError(f"GroundX ingest ended with status: {status}")

Ingest is asynchronous — don’t read the extraction until status reaches complete.

Read The Extracted JSON

Once ingest completes, look up documents in the bucket, find the one whose process_id matches, then request the extracted JSON:

1 lookup = client.documents.lookup(id=bucket_id, status="complete", n=100)
2 
3 document = next(
4     (item for item in lookup.documents or [] if item.process_id == process_id),
5     None,
6 )
7 
8 if document is None:
9     raise RuntimeError("Could not find the completed GroundX document")
10 
11 extraction = client.documents.get_extract(document.document_id)
12 print(extraction)

The result uses the same names you chose in the YAML.

For chunk- or section-level custom workflow steps, get_extract can currently return a 404 in some hosted environments even when the workflow ran correctly. This is current platform behavior, not a sign the extraction failed; see Custom workflow steps for why.

Improve The Results

When a value is missing or wrong, change the smallest part of the YAML that explains the miss — not the whole schema.

Ask the agent: "The due_date came back empty for this statement — can you
check why and fix just that value?"

The agent can compare the document against the extracted result, find which value’s description or instructions are too vague or don’t match how this document prints the value, and adjust just that part of the YAML. Then it updates the workflow, re-ingests, and reads the extraction again to confirm the fix.

Change one value at a time. If several values under the same top-level object are wrong, it’s often the shared instructions for that object that need adjusting rather than each value individually.

When To Use Agent Harness

An agent is useful throughout this loop, not just for the first draft:

Drafting the initial schema from a plain description of what you need.
Comparing the extracted JSON against expected values you provide, and telling you which fields matched and which didn’t.
Inspecting the document and the extracted result together to explain why a value came back wrong or empty.
Suggesting the smallest YAML change likely to fix a specific miss, rather than rewriting the schema from scratch.

The agent handles the schema iteration and the GroundX SDK calls shown above. How the harness turns a schema into a running workflow is internal implementation detail, documented separately in the GroundX Agent Harness project, not in this public guide.