npm package: @nampham1106/deepagents
Description: General purpose 'deep agent' with sub-agent spawning, todo list capabilities, and mock file system. Built on LangGraph.
Author: DeepAgents Team
Latest version: 0.0.4

# 🧠🤖 Deep Agents - TypeScript Edition

A powerful TypeScript implementation of Deep Agents - create and chat with AI agents that have subagent spawning capabilities, todo list management, and MCP (Model Context Protocol) integration. Built on LangGraph.js and LangChain.js.

## Features

- **🚀 TypeScript Native**: Fully typed, modern TypeScript implementation
- **🤖 Subagent Spawning**: Create specialized subagents for specific tasks
- **📝 Task Management**: Built-in todo list capabilities for planning
- **🔧 MCP Support**: Connect to Model Context Protocol servers for extended tools
- **💾 Memory Persistence**: Conversation memory with checkpointing
- **🎨 Beautiful CLI**: Interactive command-line interface with colors and effects
- **🛠️ Extensible Tools**: Easy to add custom tools and integrations

## Installation

### Prerequisites

- Node.js 18+ 
- npm or yarn
- API keys for either:
  - OpenAI (OPENAI_API_KEY)
  - Anthropic Claude (ANTHROPIC_API_KEY)

### Install from npm

```bash
npm install -g @nampham1106/deepagents
```

### Or install as dependency

```bash
npm install @nampham1106/deepagents
```

## Quick Start

### 1. Set up your API keys

Create a `.env` file in your project root:

```env
# Choose one or both
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
```

### 2. Initialize DeepAgents

```bash
deepagents init
```

### 3. Start Interactive Mode

```bash
deepagents -i
```

### 4. Create Your First Agent

In the interactive CLI:

```
deepagents > /create my-assistant
```

### 5. Chat with Your Agent

```
my-assistant > Help me write a TypeScript function
```

## CLI Commands

### Interactive Mode Commands

- `/create <name>` - Create a new agent with optional subagents
- `/chat <message>` - Send a message to the current agent
- `/subagents` - List available subagents
- `/tools` - View available tools
- `/mcp` - Manage MCP servers
- `/clear` - Clear the screen
- `/help` - Show help
- `/exit` - Exit the CLI

### Command Line Usage

```bash
# Interactive mode
deepagents -i

# Initialize
deepagents init
```

## Programmatic API

### Basic Usage

```typescript
import { createDeepAgent } from "@nampham1106/deepagents";
import { ChatOpenAI } from "@langchain/openai";

// Create an agent
const agent = await createDeepAgent({
  tools: [],
  instructions: "You are a helpful AI assistant.",
  model: new ChatOpenAI({ model: "gpt-4" }),
  useMemory: true,
});

// Use the agent
const result = await agent.invoke({
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(result.messages[result.messages.length - 1].content);
```

### Azure OpenAI Integration

```typescript
import { createDeepAgent, createAzureOpenAIModel } from "@nampham1106/deepagents";

// Create an Azure OpenAI model
const azureModel = createAzureOpenAIModel(
  "gpt-4-deployment",           // deployment name
  "my-instance",                // instance name
  "your-api-key",               // API key (optional if set in env)
  "2024-02-01"                  // API version (optional)
);

// Create an agent with Azure OpenAI
const agent = await createDeepAgent({
  tools: [],
  instructions: "You are a helpful AI assistant.",
  model: azureModel,
  useMemory: true,
});
```

### With Subagents

```typescript
import { createDeepAgent, SubAgent } from "@nampham1106/deepagents";

const codeReviewer: SubAgent = {
  name: "code-reviewer",
  description: "Expert at reviewing code",
  instructions: "You are an expert code reviewer...",
  tools: ["read_file", "write_file"],
};

const agent = await createDeepAgent({
  tools: [],
  instructions: "You are the main coordinator.",
  subagents: [codeReviewer],
});
```

### Custom Tools

```typescript
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const customTool = tool(
  async ({ input }: { input: string }) => {
    // Your tool logic here
    return `Processed: ${input}`;
  },
  {
    name: "custom_tool",
    description: "A custom tool",
    schema: z.object({
      input: z.string().describe("The input to process"),
    }),
  }
);

const agent = await createDeepAgent({
  tools: [customTool],
  instructions: "You have access to a custom tool.",
});
```

## Built-in Tools

- **read_file** - Read files from the filesystem
- **write_file** - Create or overwrite files
- **edit_file** - Edit existing files
- **ls** - List directory contents
- **write_todos** - Manage task lists

## Subagents

Subagents are specialized agents that can be invoked for specific tasks. They are defined as Markdown files with YAML frontmatter in the `.deepagents/subagents/` directory.

### Example Subagent

```markdown
---
name: test-writer
description: Expert at writing tests
tools:
  - read_file
  - write_file
  - edit_file
---

You are an expert test writer. Your job is to write comprehensive tests
for the code provided. Always ensure good test coverage.
```

## MCP (Model Context Protocol) Support

Connect to MCP servers for additional tools:

```bash
# In interactive mode
/mcp add --transport http context7 https://mcp.context7.com/mcp
/mcp add --transport stdio filesystem npx @modelcontextprotocol/server-filesystem /tmp

# List servers
/mcp

# Check status
/mcp status
```

Popular MCP servers:
- **Context7**: Web search and content extraction
- **DeepWiki**: GitHub repository documentation
- **Filesystem**: Local file system access
- **SQLite**: Database operations

## Architecture

```
src/
├── cli/            # CLI implementation
│   ├── main.ts     # CLI entry point
│   └── effects.ts  # Terminal effects
├── mcp/            # MCP integration
│   └── manager.ts  # MCP manager
├── subagents/      # Subagent management
│   └── manager.ts  # Subagent loader
├── graph.ts        # Core agent creation (LangGraph)
├── model.ts        # LLM model configuration
├── state.ts        # Agent state management
├── tools.ts        # Built-in tools
├── prompts.ts      # System prompts
├── subagent.ts     # Subagent implementation
└── index.ts        # Main exports
```

## Configuration

### Environment Variables

Create a `.env` file in your project root or in `~/.deepagents/.env`:

```bash
# Choose one or more:

# Azure OpenAI (recommended for enterprise)
AZURE_OPENAI_API_KEY=your-azure-openai-api-key
AZURE_OPENAI_API_INSTANCE_NAME=your-instance-name
AZURE_OPENAI_API_DEPLOYMENT_NAME=your-deployment-name
AZURE_OPENAI_API_VERSION=2024-02-01  # Optional, defaults to 2024-02-01

# OpenAI API Key (for GPT models)
OPENAI_API_KEY=your-openai-api-key-here

# Anthropic API Key (for Claude models)
ANTHROPIC_API_KEY=your-anthropic-api-key-here

# Optional: MCP Registry Path
MCP_REGISTRY_PATH=/path/to/mcp-registry.json

# Optional: DeepAgents Home Directory
DEEPAGENTS_HOME=~/.deepagents
```

**Priority Order**: Azure OpenAI > Anthropic > OpenAI

### Configuration File

Configuration is stored in `~/.deepagents/config.json`:

```json
{
  "effects": {
    "enabled": true,
    "theme": "ocean"
  },
  "model": "gpt-4",
  "mcp_servers": []
}
```

## Troubleshooting

### Common Issues

1. **Module not found errors**: Run `npm install` to install dependencies
2. **API key errors**: Ensure your `.env` file has valid API keys
3. **Build errors**: Run `npm run build` before running the CLI
4. **Permission errors**: Ensure the CLI script has execute permissions

### Debug Mode

Set the `DEBUG` environment variable:

```bash
DEBUG=deepagents* deepagents -i
```

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Acknowledgments

- Built on [LangGraph.js](https://github.com/langchain-ai/langgraphjs) and [LangChain.js](https://github.com/langchain-ai/langchainjs)
- Inspired by the original Python Deep Agents implementation
- MCP protocol by Anthropic

## Support

For issues and questions:
- Open an issue on GitHub
- Check the documentation

---

**Note**: This is a TypeScript implementation of Deep Agents, optimized for Node.js environments and TypeScript developers.