Skip to content

Built-in Agents

The framework ships with four pre-built agents that cover the most common AI application patterns: knowledge-base Q&A, document analysis, multi-step orchestration, and web research. All extend BaseAgent and follow the same execution lifecycle.

Import

import {
  QAChatAgent,
  DocumentAnalysisAgent,
  OrchestratorAgent,
  WebResearchAgent,
} from "@modernpath/agent-framework";

Agent Comparison

Agent Purpose Key Dependencies When to Use
QAChatAgent RAG-powered question answering RetrievalService, GeminiClient, PromptTemplate Answer user questions grounded in a knowledge base
DocumentAnalysisAgent SharePoint document operations GeminiClient, PromptTemplate, document tools List, query, analyze, compare, extract, or summarize documents
OrchestratorAgent Multi-step task planning and execution GeminiClient, PromptTemplate, atomic agents Complex tasks that require multiple agents working together
WebResearchAgent Web search and URL context analysis GeminiClient Gather information from the public web with citations

Architecture

The agents are designed in two tiers:

Atomic agents perform a single, focused task:

  • QAChatAgent -- retrieves context from a knowledge store and generates an answer
  • DocumentAnalysisAgent -- performs document operations (list, query, analyze, etc.)
  • WebResearchAgent -- searches the web and analyzes URLs

The orchestrator composes atomic agents into multi-step workflows:

  • OrchestratorAgent -- uses an LLM to generate a task plan, then executes each step by delegating to atomic agents or registered tools
graph TD
    User[User Request] --> O[OrchestratorAgent]
    O -->|step 1| DA[DocumentAnalysisAgent]
    O -->|step 2| QA[QAChatAgent]
    O -->|step 3| WR[WebResearchAgent]
    O -->|step 4| DT[Dynamic Tool]
    DA --> Result
    QA --> Result
    WR --> Result
    DT --> Result
    Result[Aggregated Result] --> User

Common Patterns

Direct Agent Invocation

For single-purpose tasks, invoke an agent directly:

const qaAgent = new QAChatAgent(registry, retrieval, gemini, prompts, {
  defaultStore: "company-knowledge-base",
});

const result = await qaAgent.execute({
  userId: 1,
  auditingId: 100,
  prompt: "What is the refund policy?",
  parameters: { store: "company-knowledge-base" },
});

console.log(result.data.answer);

Orchestrated Multi-step Workflow

For complex tasks, let the orchestrator plan and coordinate:

const orchestrator = new OrchestratorAgent(
  registry,
  gemini,
  prompts,
  { documentAnalysis: docAgent, qaChat: qaAgent },
);

const result = await orchestrator.execute({
  userId: 1,
  auditingId: 100,
  prompt: "Analyze last quarter's financial reports and summarize the key findings",
  parameters: {},
});

console.log(result.data.plan);       // The generated task plan
console.log(result.data.aggregated); // Combined results from all steps

Shared Tool Registry

All agents in a deployment typically share the same ToolRegistry:

const registry = new ToolRegistry();

// Register SharePoint document tools
registry.register("documentList", documentListTool);
registry.register("documentRetrieve", documentRetrieveTool);
registry.register("documentQuery", documentQueryTool);

// Register external integration tools
registerDynamicTool(registry, ticketCreateDefinition);
registerDynamicTool(registry, notificationDefinition);

// All agents share the same registry
const docAgent = new DocumentAnalysisAgent(registry, gemini, prompts);
const qaAgent = new QAChatAgent(registry, retrieval, gemini, prompts);
const orchestrator = new OrchestratorAgent(
  registry, gemini, prompts,
  { documentAnalysis: docAgent, qaChat: qaAgent },
);

Agent Outputs

Each agent returns its result in AgentResult.data. The structure varies by agent:

Agent data Shape
QAChatAgent { answer: string, sources: KnowledgeSource[], groundingMetadata? }
DocumentAnalysisAgent Varies by action -- see DocumentAnalysisAgent
OrchestratorAgent { plan: TaskPlan, results: StepResult[], aggregated: AggregatedResult }
WebResearchAgent { answer: string, groundingMetadata?, urlContextMetadata?, urlsUsed: string[] }