🧠🤖 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

npm install -g @nampham1106/deepagents

Or install as dependency

npm install @nampham1106/deepagents

Quick Start

1. Set up your API keys

Create a .env file in your project root:

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

2. Initialize DeepAgents

deepagents init

3. Start Interactive Mode

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

# Interactive mode
deepagents -i

# Initialize
deepagents init

Programmatic API

Basic Usage

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

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

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

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

---
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:

# 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:

# 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:

{
  "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:

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 and LangChain.js
• 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.