> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Document Agent
> An autonomous AI agent that researches your indexed documents using tools — search, read, navigate — to deliver cited, structured answers
**Builder Feature** - Document Agent is included with Builder, Team, and Business plans. Free plan users can also use Document Agent with purchased credits.
## Overview
Document Agent is an autonomous AI agent that researches your indexed PDFs and documents. It doesn't just retrieve chunks — it has access to specialized tools (search, read sections, read pages, navigate document trees) and uses them iteratively, planning its own research strategy to build comprehensive answers.
Think of it as deploying an agent *into* your document. It decides what to search for, which sections to read, navigates the hierarchy, follows cross-references, and synthesizes findings — all autonomously. It supports structured output via JSON schemas, extended thinking for complex reasoning, and real-time streaming.
Use Document Agent when you need an agent that can deeply research a specific document — contracts, filings, research papers, technical manuals — with full citation traceability.
## Key Capabilities
Every claim in the response is backed by citations pointing to specific pages, sections, and content from the source document.
Provide a JSON Schema and receive structured data extracted from the document — perfect for pipelines, automation, and data processing.
The agent uses extended thinking to reason through complex queries, plan its tool usage, and synthesize multi-part answers with configurable token budgets.
Stream responses as Server-Sent Events for real-time UI updates. Watch the agent work through the document as it builds its answer.
Choose the model that fits your task — from fast and efficient to maximum capability with 1M token context windows.
The agent autonomously plans its research strategy — deciding which tools to call, what to search for, which sections to read next — rather than relying on a single retrieval pass.
***
## How It Works
Upload or provide a URL to your PDF. Nia parses it into a hierarchical document tree — sections, subsections, figures, tables — preserving structure and context.
Send a query to the Document Agent along with the `source_id` of your indexed document. Optionally provide a JSON schema for structured output.
The agent plans its research strategy using extended thinking, then autonomously calls tools in a loop — searching across sections, reading specific pages, navigating the document tree, following cross-references — until it has gathered all relevant information. You can watch this happen in real-time via streaming.
The agent produces a comprehensive answer with inline citations. Each citation links back to the exact page, section, and content in the source document. If a JSON schema was provided, the response also includes structured output conforming to your schema.
***
## API Usage
### Basic Query
Ask a question about an indexed document and receive a cited answer:
```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/document/agent \
-H "Authorization: Bearer $NIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_id": "src_abc123",
"query": "What are the key risk factors disclosed in this filing?",
"model": "claude-opus-4-7",
"thinking_enabled": true,
"thinking_budget": 10000
}'
```
**Response:**
```json theme={null}
{
"answer": "The filing identifies several key risk factors: (1) Market volatility affecting portfolio valuations [p. 23], (2) Regulatory changes in key operating jurisdictions [p. 24-25], and (3) Cybersecurity threats to customer data [p. 27]...",
"citations": [
{
"content": "Our business is subject to market volatility which may adversely affect...",
"page_number": 23,
"section_id": "sec_risk_factors_market",
"section_title": "Market Risk",
"section_path": "Risk Factors > Market Risk",
"tool_source": "read_section"
},
{
"content": "Changes in regulatory frameworks across jurisdictions in which we operate...",
"page_number": 24,
"section_id": "sec_risk_factors_regulatory",
"section_title": "Regulatory Risk",
"section_path": "Risk Factors > Regulatory Risk",
"tool_source": "search"
}
],
"model": "claude-opus-4-7",
"usage": {
"input_tokens": 15230,
"output_tokens": 1847,
"thinking_tokens": 8500
}
}
```
### Structured Output Query
Extract structured data from documents by providing a JSON schema:
```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/document/agent \
-H "Authorization: Bearer $NIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_id": "src_abc123",
"query": "Extract all parties, effective date, and termination clauses from this contract.",
"json_schema": {
"type": "object",
"properties": {
"parties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"role": { "type": "string" }
}
}
},
"effective_date": { "type": "string" },
"termination_clauses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clause_id": { "type": "string" },
"description": { "type": "string" },
"notice_period_days": { "type": "integer" }
}
}
}
},
"required": ["parties", "effective_date", "termination_clauses"]
},
"model": "claude-opus-4-7",
"thinking_enabled": true,
"thinking_budget": 15000
}'
```
**Response:**
```json theme={null}
{
"answer": "The contract is between Acme Corp (Provider) and GlobalTech Inc (Client), effective January 15, 2025. It contains two termination clauses...",
"citations": [
{
"content": "This Agreement is entered into by and between Acme Corp ('Provider') and GlobalTech Inc ('Client')...",
"page_number": 1,
"section_id": "sec_preamble",
"section_title": "Preamble",
"section_path": "Preamble",
"tool_source": "read_page"
}
],
"structured_output": {
"parties": [
{ "name": "Acme Corp", "role": "Provider" },
{ "name": "GlobalTech Inc", "role": "Client" }
],
"effective_date": "2025-01-15",
"termination_clauses": [
{
"clause_id": "8.1",
"description": "Either party may terminate for convenience with written notice",
"notice_period_days": 90
},
{
"clause_id": "8.2",
"description": "Immediate termination for material breach after cure period",
"notice_period_days": 30
}
]
},
"model": "claude-opus-4-7",
"usage": {
"input_tokens": 22100,
"output_tokens": 2340,
"thinking_tokens": 12000
}
}
```
### Streaming
Stream the response as Server-Sent Events for real-time updates:
```bash theme={null}
curl -N -X POST https://apigcp.trynia.ai/v2/document/agent \
-H "Authorization: Bearer $NIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_id": "src_abc123",
"query": "Summarize the methodology section and its limitations.",
"stream": true
}'
```
SSE events arrive as the agent works through the document, enabling responsive UIs that show progress in real time.
***
## Parameters
| Parameter | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ----------------- | ---------------------------------------------- |
| `source_id` | string | Yes | — | Data source ID of the indexed document |
| `query` | string | Yes | — | Question to ask about the document |
| `json_schema` | object | No | — | JSON Schema for structured output extraction |
| `model` | string | No | `claude-opus-4-7` | Model to use for the agent |
| `thinking_enabled` | boolean | No | `true` | Enable extended thinking for complex reasoning |
| `thinking_budget` | integer | No | `10000` | Token budget for thinking (1,000 - 50,000) |
| `stream` | boolean | No | `false` | Stream response as Server-Sent Events |
***
## Model Selection Guide
Choose the right model based on your task requirements:
| Model | Context Window | Best For | Speed | Cost |
| -------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- | -------- | -------- |
| `claude-opus-4-7` | 1M tokens | Complex reasoning over long documents, multi-step analysis, structured extraction from dense filings | Slower | Highest |
| `claude-sonnet-4-20250514` | 200K tokens | Balanced performance for most document queries, good reasoning with faster responses | Moderate | Moderate |
| `claude-haiku-35-20241022` | 200K tokens | Quick lookups, simple fact extraction, high-volume processing | Fastest | Lowest |
**Start with the default.** `claude-opus-4-7` with its 1M context window handles even the longest documents. Scale down to Sonnet or Haiku when you need faster responses or lower costs for simpler queries.
***
## Use Cases
Extract parties, obligations, termination clauses, and liability caps from contracts. Use structured output to feed data directly into case management systems.
Query 10-Ks, 10-Qs, and annual reports. Extract risk factors, revenue breakdowns, and forward-looking statements with page-level citations for audit trails.
Ask about specifications, procedures, and safety requirements. The agent navigates complex hierarchical documents to find precise answers across sections.
Interrogate methodology, results, and conclusions. Compare findings across sections. Use structured output to extract experimental parameters and metrics into tables.
### Structured Output Patterns
**Query:** "Extract quarterly revenue figures and year-over-year growth rates."
**Schema:**
```json theme={null}
{
"type": "object",
"properties": {
"quarters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"period": { "type": "string" },
"revenue_millions": { "type": "number" },
"yoy_growth_pct": { "type": "number" }
}
}
},
"fiscal_year": { "type": "string" },
"currency": { "type": "string" }
}
}
```
The agent reads the financial statements, locates revenue tables, and returns clean structured data ready for analysis.
**Query:** "Extract the paper's key details: authors, abstract, datasets used, and reported metrics."
**Schema:**
```json theme={null}
{
"type": "object",
"properties": {
"title": { "type": "string" },
"authors": { "type": "array", "items": { "type": "string" } },
"abstract": { "type": "string" },
"datasets": { "type": "array", "items": { "type": "string" } },
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"value": { "type": "number" },
"dataset": { "type": "string" }
}
}
}
}
}
```
The agent extracts structured metadata from any research paper, making it easy to build literature review databases.
**Query:** "Identify all compliance requirements and their current status mentioned in this audit report."
**Schema:**
```json theme={null}
{
"type": "object",
"properties": {
"requirements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"requirement": { "type": "string" },
"regulation": { "type": "string" },
"status": { "type": "string", "enum": ["compliant", "non_compliant", "partially_compliant", "not_assessed"] },
"findings": { "type": "string" },
"page_reference": { "type": "integer" }
}
}
}
}
}
```
Turn unstructured audit reports into actionable compliance checklists with a single API call.
***
## Document Agent vs. Standard Search
| Aspect | Document Agent | Nia Search |
| --------------------- | ----------------------------------------------------------------------- | ----------------------------------------- |
| **Approach** | Autonomous agent — plans strategy, calls tools in a loop, follows leads | Single-pass retrieval over indexed chunks |
| **Citations** | Page, section, and content-level citations | Source-level citations |
| **Structured Output** | JSON Schema support for typed extraction | Not available |
| **Thinking** | Extended thinking with configurable budgets | Not available |
| **Best For** | Complex questions requiring reasoning across sections | Quick factual lookups |
| **Latency** | Higher (multi-step agent loop) | Lower (single retrieval) |
**Use Document Agent when:**
* Your question requires synthesizing information from multiple sections
* You need structured data extracted from documents
* You need page-level citation traceability
* The question requires reasoning, not just retrieval
**Use Nia Search when:**
* You need fast, simple lookups across many sources
* Low latency is critical
* The question maps directly to a specific passage