npm package: @morphllm/subagents
Description: Subagent SDK - planning, filesystem, subagents, teams, DOCX, and more
Latest version: 0.2.1

# @morphllm/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 @morphllm/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)

```typescript
import { DocxClient } from '@morphllm/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)

```typescript
import OpenAI from 'openai';
import { DocxClient, DocxAgent } from '@morphllm/subagents/docx';

const openai = new OpenAI();
const client = new DocxClient();

// Upload a document first
const file = new File([documentBuffer], 'contract.docx');
const { doc_id } = await client.upload(file);

// Create agent with the document
const agent = new DocxAgent({
  openai,
  documentId: 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);

// Download the edited document
const editedDoc = await client.download(doc_id);
```

### Streaming Responses

```typescript
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 '@morphllm/subagents';

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

## Building Custom Subagents

Extend the base classes to create your own subagents:

```typescript
import { BaseClient, BaseAgent } from '@morphllm/subagents/core';
import type { Tool } from '@morphllm/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 | https://docx.morphllm.com |

## License

MIT