DocumentAnalysisAgent¶

Agent for performing document operations against SharePoint-hosted documents via the Gemini model. Supports eight actions: listing, selecting, querying, analyzing, comparing, extracting, summarizing, and general-purpose analysis. The agent classifies intent automatically when no explicit action is provided.

Import¶

import { DocumentAnalysisAgent } from "@modernpath/agent-framework";

Constructor¶

class DocumentAnalysisAgent extends BaseAgent {
  constructor(
    toolRegistry: ToolRegistry,
    gemini: GeminiClient,
    prompts: PromptTemplate,
  )
}

Supported Actions¶

The agent dispatches to one of eight actions based on context.parameters.action. If no action is specified, the agent uses LLM-based intent classification to determine the appropriate action.

Context Parameters¶

The agent reads these keys from AgentContext.parameters:

Required Tools¶

The agent invokes these tools via the ToolRegistry. Register them before constructing the agent:

Return Value¶

The structure of AgentResult.data depends on the action:

{
  documents: Array<{
    id: string;
    name: string;
    // ... additional document metadata
  }>;
}

{
  selectedDocumentIds: string[];
  candidates: Array<{ id: string; name: string; ... }>;
}

{
  // Query result from documentQuery tool
}

string  // Direct LLM analysis text

{
  // Analysis result from documentAnalyze tool
}

{
  // Comparison result from documentCompare tool
}

{
  message: "Provide parameters.documentIds (2+).";
  candidates: Array<{ id: string; name: string; ... }>;
}

{
  // Result from documentExtract or documentSummarize tool
}

Intent Classification¶

When parameters.action is not set, the agent classifies the user's intent using the Gemini model with low temperature (0.1) and a maximum of 10 output tokens. The classification prompt is rendered from:

• document-analysis.intent_classification.system -- system prompt (optional)
• document-analysis.intent_classification.user_template -- user prompt with prompt and history variables

The model returns one of: query, list, select, compare, extract, summarize, analyze, general.

Execution Flow¶

flowchart TD
    Start[execute] --> HasAction{action provided?}
    HasAction -->|Yes| Dispatch
    HasAction -->|No| Classify[LLM intent classification]
    Classify --> Dispatch{action}
    Dispatch -->|list| List[documentList tool]
    Dispatch -->|select| Select[documentList + documentSelect]
    Dispatch -->|query| Query[documentRetrieve + documentQuery/LLM]
    Dispatch -->|analyze| Analyze[auto-select + documentAnalyze]
    Dispatch -->|compare| Compare[documentCompare]
    Dispatch -->|extract| Extract[documentExtract]
    Dispatch -->|summarize| Summarize[documentSummarize]
    Dispatch -->|general| General[Unsupported action message]

Code Example¶

List Documents¶

import { DocumentAnalysisAgent, ToolRegistry } from "@modernpath/agent-framework";

const registry = new ToolRegistry();
// Register document tools...
registry.register("documentList", documentListTool);

const agent = new DocumentAnalysisAgent(registry, geminiClient, prompts);

const result = await agent.execute({
  userId: 42,
  auditingId: 1001,
  prompt: "Show me all documents",
  parameters: {
    action: "list",
    siteId: "site-abc-123",
    folderPath: "/Shared Documents/Finance",
    fileTypes: ["pdf", "xlsx"],
    pageSize: 20,
  },
});

if (result.success) {
  for (const doc of result.data.documents) {
    console.log(`${doc.name} (${doc.id})`);
  }
}

Query a Document¶

const result = await agent.execute({
  userId: 42,
  auditingId: 1001,
  prompt: "What was the total revenue in Q3?",
  parameters: {
    action: "query",
    siteId: "site-abc-123",
    documentId: "doc-xyz-789",
  },
});

Compare Documents¶

const result = await agent.execute({
  userId: 42,
  auditingId: 1001,
  prompt: "Compare the budget proposals for Q3 and Q4",
  parameters: {
    action: "compare",
    siteId: "site-abc-123",
    documentIds: ["doc-q3-budget", "doc-q4-budget"],
    comparisonType: "financial",
  },
});

Auto-classify Intent¶

// No action specified -- the agent classifies intent from the prompt
const result = await agent.execute({
  userId: 42,
  auditingId: 1001,
  prompt: "Summarize the annual report",
  parameters: {
    siteId: "site-abc-123",
    documentId: "doc-annual-report",
  },
});
// Agent classifies intent as "summarize" and calls documentSummarize

Related Pages¶

• BaseAgent -- base class and execution lifecycle
• ToolRegistry -- registering document tools
• OrchestratorAgent -- using DocumentAnalysisAgent as an atomic agent
• SharePoint Integration -- the underlying SharePoint access layer
• Document Processing -- parsing and querying documents