Skip to content

README.md

Latest commit

 

History

History
150 lines (104 loc) · 4.26 KB

README.md

File metadata and controls

150 lines (104 loc) · 4.26 KB

Deep Research Agent

A powerful AI research agent built with TypeScript, LangChain, and DeepAgents that conducts thorough research and generates detailed markdown reports.

🌟 Features

  • Intelligent Research: Automatically searches the web for information using Tavily API
  • Task Management: Creates and manages to-do lists for research workflows
  • File Operations: Read, write, and edit files programmatically
  • Real-time Streaming: See the agent's progress in real-time with streaming updates
  • Markdown Reports: Generates well-structured research reports with sources
  • OpenAI Integration: Powered by GPT-4o-mini for intelligent decision-making

🚀 Getting Started

Prerequisites

  • Node.js (v18 or higher)
  • npm or yarn
  • OpenAI API key
  • Tavily API key

Installation

  1. Clone the repository:
git clone https://github.com/yourusername/deep-research-agent-typescript.git
cd deep-research-agent-typescript
  1. Install dependencies:
npm install
  1. Create a .env file in the root directory:
OPENAI_API_KEY=your_openai_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here

Usage

Run the research agent:

npm start

The agent will:

  1. Create a to-do list for the research task
  2. Search for relevant information
  3. Generate a detailed markdown report
  4. Save the report to a file

🛠️ Available Tools

The agent has access to the following tools:

Custom Tools

  • internet_search: Search the web using Tavily API with configurable parameters

Built-in FilesystemBackend Tools

  • ls: List files in a directory with metadata (size, modified time)
  • read_file: Read file contents with line numbers, supports offset/limit for large files
  • write_file: Create new files in the working directory
  • edit_file: Perform exact string replacements in files (with global replace mode)
  • glob: Find files matching patterns (e.g., **/*.py, src/**/*.ts)
  • grep: Search file contents with multiple output modes (files only, content with context, or counts)

📁 Project Structure

deep-research-agent-typescript/
├── tools/
│   ├── search_tool.ts      # Internet search functionality (Tavily API)
│   └── agent_tools.ts      # Custom tool examples (optional)
├── deep_agent.ts           # Main agent configuration with FilesystemBackend
├── package.json            # Project dependencies
├── tsconfig.json           # TypeScript configuration
├── .env                    # Environment variables (not tracked)
├── .env.example            # Environment template
├── .gitignore              # Git ignore rules
├── LICENSE                 # ISC License
├── README.md               # This file
├── SETUP.md                # Detailed setup guide
└── CONTRIBUTING.md         # Contribution guidelines

🔧 Configuration

You can customize the agent by modifying deep_agent.ts:

Model Configuration

  • Model: Change the OpenAI model (default: gpt-4o-mini)
  • Temperature: Adjust creativity (default: 0 for deterministic output)
  • System Prompt: Customize the agent's behavior and instructions
  • Recursion Limit: Set maximum steps (default: 50)

FilesystemBackend Configuration

  • rootDir: Set the working directory for file operations (default: .)
  • virtualMode: Enable safe mode with validation (default: true)
backend: new FilesystemBackend({
  rootDir: ".", // Current directory
  virtualMode: true, // Safe mode enabled
});

📝 Example Output

The agent generates markdown reports with:

  • Title and introduction
  • Main findings with sources
  • Detailed analysis
  • Conclusion
  • Timestamp

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the ISC License.

🙏 Acknowledgments

📧 Contact

For questions or feedback, please open an issue on GitHub.

Made with ❤️ using TypeScript and AI