subagents

Modular AI subagents for document processing. Built for use with OpenAI-compatible APIs.

How It Works

Subagents follow the "Agents as Tools" pattern—specialized secondary agents that your main agent delegates to for domain-specific tasks:

                              ┌─────────────────────┐
                              │     MAIN AGENT      │
                              │                     │
                              │  • Orchestrates     │
                              │  • Plans            │
                              │  • Delegates        │
                              └──────────┬──────────┘
                                         │
            ┌────────────────────────────┼────────────────────────────┐
            │                            │                            │
            ▼                            ▼                            ▼
   ┌─────────────────┐          ┌─────────────────┐          ┌─────────────────┐
   │   DOCX AGENT    │          │   PDF AGENT     │          │   YOUR AGENT    │
   │                 │          │                 │          │                 │
   │  "Review this   │          │  "Fill out      │          │  Domain-specific│
   │   contract"     │          │   this form"    │          │  capabilities   │
   └────────┬────────┘          └────────┬────────┘          └────────┬────────┘
            │                            │                            │
            ▼                            ▼                            ▼
   ┌─────────────────┐          ┌─────────────────┐          ┌─────────────────┐
   │  Track changes  │          │  Form filling   │          │  Custom tools   │
   │  Comments       │          │  Annotations    │          │  & APIs         │
   │  Document edits │          │  (Coming soon)  │          │                 │
   └─────────────────┘          └─────────────────┘          └─────────────────┘

The main agent handles orchestration and planning. When it encounters a specialized task (editing a Word doc, filling a PDF form), it delegates to the appropriate subagent which handles all the domain complexity—file formats, APIs, and tool execution.

Installation

npm install subagents

Available Subagents

| Subagent | Description | Status | |----------|-------------|--------| | DOCX | Track changes, comments, and document editing | Available | | PDF | Form filling and annotations | Coming Soon |

Quick Start

DOCX Client (Direct API Access)

import { DocxClient } from 'subagents/docx';

const client = new DocxClient();

// Upload a document
const doc = await client.upload(file);

// Read content
const content = await client.read(doc.doc_id);

// Add comments and track changes
await client.edit(doc.doc_id, [
  { type: 'add_comment', para_text: 'Introduction', comment: 'Needs citation' },
  { type: 'insert_text', para_text: 'Introduction', after: '.', new_text: ' [1]' },
]);

// Download the edited document
const blob = await client.download(doc.doc_id);

DOCX Agent (AI-Powered)

import OpenAI from 'openai';
import { DocxAgent } from 'subagents/docx';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const agent = new DocxAgent({
  openai,
  documentId: 'your-doc-id',
});

// Run with natural language
const result = await agent.run('Review this contract and flag any issues');
console.log(result.response);
console.log(result.toolCalls);

// Or stream for real-time UI
for await (const event of agent.runStream('Add comments to unclear sections')) {
  if (event.type === 'content_delta') {
    process.stdout.write(event.delta.text);
  } else if (event.type === 'tool_start') {
    console.log(`\nExecuting: ${event.tool.name}`);
  }
}

Module Imports

// Import everything
import { DocxClient, DocxAgent, BaseClient } from 'subagents';

// Import specific modules
import { DocxClient, DocxAgent } from 'subagents/docx';
import { BaseClient, BaseAgent } from 'subagents/core';

Building Custom Subagents

Extend the base classes to create your own subagents:

import { BaseClient, BaseAgent } from 'subagents/core';
import type { Tool } from 'subagents/core';

class MyClient extends BaseClient {
  protected getDefaultApiUrl() {
    return 'https://my-api.example.com';
  }

  async myMethod() {
    return this.get('/my-endpoint');
  }
}

class MyAgent extends BaseAgent<MyClient> {
  protected getDefaultModel() {
    return 'gpt-4';
  }

  protected getDefaultInstructions() {
    return 'You are a helpful assistant.';
  }

  protected getTools(): Tool[] {
    return [/* your tools */];
  }

  protected async executeTool(name: string, args: Record<string, unknown>) {
    // Execute tool calls
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | DOCX_API_URL | DOCX service URL | Railway deployment |

License

MIT