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

`bash
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

$3

`typescript
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);
`

$3

`typescript
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

`typescript
// 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:

`typescript
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 {
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) {
// Execute tool calls
}
}
`

Environment Variables

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

License

MIT