This is a starter template for building AI agents using LangGraph and CopilotKit. It provides a modern Next.js application with an integrated LangGraph agent to be built on top of.
- Node.js 18+
- Python 3.8+
- Any of the following package managers:
- OpenAI API Key (for the LangGraph agent)
The project automatically selects between OpenAI and local Ollama models:
Automatic Fallback Pattern:
- If
OPENAI_API_KEYis set and not empty → Uses OpenAI - If
OPENAI_API_KEYis empty or unset → Uses local Ollama
Customize models and settings in agent/.env:
# Model temperature (0-1)
MODEL_TEMPERATURE=0
# OpenAI settings (uncomment to use OpenAI)
# OPENAI_API_KEY=your-api-key
# OPENAI_MODEL=gpt-4o
# Ollama settings (used when no OpenAI key)
OLLAMA_MODEL=llama3.2:3b
OLLAMA_BASE_URL=http://localhost:11434
# LangSmith (optional - for monitoring/debugging)
# LANGSMITH_API_KEY=your-langsmith-api-key
# LANGSMITH_PROJECT=your-project-nameNote: This repository ignores lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) to avoid conflicts between different package managers. Each developer should generate their own lock file using their preferred package manager. After that, make sure to delete it from the .gitignore.
- Install dependencies using your preferred package manager:
# Using pnpm (recommended)
pnpm install
# Using npm
npm install
# Using yarn
yarn install
# Using bun
bun install- Install dependencies for the LangGraph agent:
cd agent# Using pnpm (recommended)
pnpm install
# Using npm
npm run install
# Using yarn
yarn install
# Using bun
bun run install- Set up local models (Ollama):
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Pull a model (e.g., llama3.2)
ollama pull llama3.2
# Start Ollama (runs on http://localhost:11434)
ollama serveAlternatively, to use OpenAI:
cd agent
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env- (Optional) Set up environment variables in
.env.local:
# CopilotKit Cloud (optional)
echo "COPILOT_CLOUD_PUBLIC_API_KEY=your-copilotkit-key" >> .env.local
# MCP Server API Keys (optional)
echo "BRAVE_API_KEY=your-brave-api-key" >> .env.local
echo "GITHUB_PERSONAL_ACCESS_TOKEN=your-github-token" >> .env.local
echo "NEXT_PUBLIC_OPENWEATHER_API_KEY=your-openweather-api-key" >> .env.localAPI Key Sources:
- CopilotKit: Get from https://cloud.copilotkit.ai
- Brave Search: Sign up at https://api.search.brave.com/
- GitHub: Generate at https://github.com/settings/tokens
- Start the development server:
# Using pnpm (recommended)
pnpm dev
# Using npm
npm run dev
# Using yarn
yarn dev
# Using bun
bun run devThis will start both the UI and agent servers concurrently.
The following scripts can also be run using your preferred package manager:
dev- Starts both UI and agent servers in development modedev:studio- Starts the UI and agent with LangGraph Studiodev:debug- Starts development servers with debug logging enableddev:ui- Starts only the Next.js UI serverdev:agent- Starts only the LangGraph agent serverdev:agent:studio- Starts the LangGraph agent server with LangGraph Studiobuild- Builds the Next.js application for productionstart- Starts the production serverlint- Runs ESLint for code lintingtest- Runs all tests from both agent and apptest:watch- Runs tests in watch modetest:coverage- Runs tests with unified coverage reportinstall:agent- Installs Python dependencies for the agent
The project includes comprehensive testing for both the agent and application code:
# Run all tests
npm test
# Run tests with coverage report
npm run test:coverage
# Run tests in watch mode
npm run test:watchTest Coverage:
- Agent: 97.61% coverage (LangGraph workflows, tools, model provider)
- App: 88.88% coverage (WeatherService, location utilities)
- Overall: 93.69% unified coverage
Tests are automatically discovered from:
agent/src/**/*.test.ts- Agent-specific testssrc/**/*.test.ts- Application tests
This project is configured with multiple Model Context Protocol (MCP) servers to enhance AI agent capabilities:
- CopilotKit (
https://mcp.copilotkit.ai/sse): Enhanced AI capabilities and tool orchestration - Fetch: Make HTTP requests, call APIs, scrape websites for real-time data
- Filesystem: Read/write project files, navigate directories, manage codebase
- Brave Search: Search web for documentation, tutorials, and current information
- GitHub: Access repositories, search code, read documentation, manage issues
- TypeScript: Analyze code, check types, provide IntelliSense suggestions
- ESLint: Lint code, enforce style rules, suggest best practices
- Puppeteer: Automate browsers, test React components, take screenshots
With these MCP servers, your agent can:
- "How do I add authentication?" → Search web + read your files + suggest implementation
- "Fix TypeScript errors" → Analyze code + provide fixes + update files
- "Find React examples" → Search GitHub + fetch code samples + explain patterns
- "Test this component" → Use Puppeteer + create automated tests
- "Get latest package info" → Fetch from npm API + suggest updates
Add these to your .env.local file in the project root:
# CopilotKit Cloud (optional)
COPILOT_CLOUD_PUBLIC_API_KEY=your-copilotkit-api-key
# MCP Server API Keys (optional)
BRAVE_API_KEY=your-brave-api-key
GITHUB_PERSONAL_ACCESS_TOKEN=your-github-tokenThe main UI component is in src/app/page.tsx. You can:
- Modify the theme colors and styling
- Add new frontend actions
- Utilize shared-state
- Customize your user-interface for interactin with LangGraph
- CopilotKit Documentation - Explore CopilotKit's capabilities
- LangGraph Documentation - Learn more about LangGraph and its features
- Next.js Documentation - Learn about Next.js features and API
Feel free to submit issues and enhancement requests! This starter is designed to be easily extensible.
This project is licensed under the MIT License - see the LICENSE file for details.
If you see "I'm having trouble connecting to my tools", make sure:
- The LangGraph agent is running on port 8123
- Your OpenAI API key is set correctly
- Both servers started successfully
If MCP servers aren't working:
- Ensure required environment variables are set
- Check that MCP packages are installed globally:
npm install -g @modelcontextprotocol/server-* - Verify API keys for Brave Search and GitHub
If tests are failing:
- Ensure all dependencies are installed:
npm install - Check that mock data files exist in
src/lib/services/mocks/ - Run tests with verbose output:
npm test -- --verbose