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

$3

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

$3

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

$3

`bash
npm install @nampham1106/deepagents
`

Quick Start

$3

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
`

$3

`bash
deepagents init
`

$3

`bash
deepagents -i
`

$3

In the interactive CLI:

`
deepagents > /create my-assistant
`

$3

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

CLI Commands

$3

- /create - Create a new agent with optional subagents
- /chat - 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

$3

`bash


Interactive mode

deepagents -i

Initialize

deepagents init
`

Programmatic API

$3

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

$3

`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,
});
`

$3

`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],
});
`

$3

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

$3

`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

$3

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

$3

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

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

Troubleshooting

$3

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

$3

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