# Agent Studio Starter

> Stop building AI agents from scratch. Bootstrap starter Agent app with LangGraph, CopilotKit, and beautiful Generative UIs.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nsphung-agent-studio-starter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nsphung](https://agentstack.voostack.com/s/nsphung)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [nsphung](https://github.com/nsphung)
- **Source:** https://github.com/nsphung/agent-studio-starter
- **Website:** https://www.linkedin.com/in/nsphung/

## Install

```sh
agentstack add mcp-nsphung-agent-studio-starter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# LangGraph Deep Agents + CopilotKit Generative UI Template
[](https://opensource.org/licenses/Apache-2.0)
[](https://deepwiki.com/nsphung/agent-studio-starter)

| | |
| --- | --- |
| Backend | [](https://github.com/astral-sh/uv) [](https://github.com/astral-sh/ruff) [](https://mypy-lang.org/) [](https://docs.python.org/3/whatsnew/3.13.html) |
| Frontend | [](https://nextjs.org/) |

A starter template for building **AI agent applications** with beautiful generative UIs, combining [LangChain Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) (LangGraph-powered backend) and [CopilotKit](https://docs.copilotkit.ai/) (React frontend with generative UI). This project demonstrates a weather assistant application that showcases real-time tool calling with custom UI components.

## 🎯 Project Overview

This is a **project bootstrap/demonstration** that serves as a template for building AI agent applications with:

- **Backend**: Python FastAPI service using LangChain Deep Agents framework for intelligent agent orchestration
- **Frontend**: Next.js application with CopilotKit for generative UI and real-time agent interaction
- **Infrastructure**: Kubernetes deployment with Skaffold for streamlined local development

### Key Features

✨ **Deep Agents Framework** - Built on LangGraph with support for:
- Complex multi-step task planning
- Tool usage and sub-agent delegation
- Long-term memory with checkpointing
- Streaming responses

🎨 **Generative UI** - Dynamic UI components rendered based on agent tool calls:
- Custom weather cards with animations
- Real-time status updates
- Beautiful gradients and responsive design

🚀 **Kubernetes-Native** - deployment:
- Container orchestration
- Service mesh with Skaffold
- Hot reloading for development
- Multi-service architecture

---

## 🏗️ Architecture

### High-Level System Architecture

```mermaid
graph TB
    subgraph "Frontend - Next.js + CopilotKit"
        UI[React UI]
        CK[CopilotKit Runtime]
        RT[useRenderToolCall Hook]
    end
    
    subgraph "Backend - FastAPI + Deep Agents"
        API[FastAPI Server]
        DA[Deep Agent Graph]
        LLM[LLM - ChatLiteLLM]
        TOOLS[Tools - get_weather]
        MEM[Memory Checkpointer]
    end
    
    subgraph "Kubernetes Cluster"
        FS[Frontend Service]
        BS[Backend Service]
    end
    
    UI --> CK
    CK --> |HTTP| API
    API --> DA
    DA --> LLM
    DA --> TOOLS
    DA --> MEM
    CK --> RT
    RT --> |Render Tool Calls| UI
    
    FS --> UI
    BS --> API
    
    style UI fill:#61dafb
    style CK fill:#0ea5e9
    style DA fill:#f59e0b
    style LLM fill:#8b5cf6
```

### Data Flow - Tool Call with Generative UI

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant CopilotKit
    participant Backend
    participant DeepAgent
    participant LLM
    participant Tool
    
    User->>Frontend: "What's the weather in SF?"
    Frontend->>CopilotKit: Send message
    CopilotKit->>Backend: POST /api/copilotkit
    Backend->>DeepAgent: Process message
    DeepAgent->>LLM: Generate response
    LLM->>DeepAgent: Call get_weather tool
    DeepAgent->>Tool: get_weather("San Francisco")
    Tool-->>DeepAgent: Weather data (JSON)
    DeepAgent-->>Backend: Tool result
    Backend-->>CopilotKit: Stream response
    CopilotKit->>Frontend: Tool call event
    Frontend->>Frontend: useRenderToolCall renders custom UI
    Frontend-->>User: Beautiful weather card 🌤️
```

### Component Architecture

```mermaid
graph LR
    subgraph "Backend Container :8123"
        MAIN[main.py]
        UTILS[utils.py]
        AGUI[ag_ui_langgraph]
        CKBE[CopilotKit Backend]
        
        MAIN --> UTILS
        MAIN --> AGUI
        UTILS --> |create_deep_agent| DA[Deep Agent Graph]
        AGUI --> |LangGraphAGUIAgent| CKBE
    end
    
    subgraph "Frontend Container :3000"
        PAGE[page.tsx]
        ROUTE[route.ts]
        CKRT[CopilotRuntime]
        UI[Generative UI]
        
        PAGE --> UI
        ROUTE --> CKRT
        CKRT --> |LangGraphHttpAgent| HTTP
    end
    
    HTTP[HTTP Client] --> |http://backend:8123| CKBE
    
    style DA fill:#f59e0b
    style UI fill:#61dafb
    style CKBE fill:#0ea5e9
    style CKRT fill:#0ea5e9
```

---

## 🐍 Backend - Deep Agents with LangGraph

The backend is a FastAPI service that uses the **Deep Agents framework** - an agent harness built on top of LangGraph for complex, multi-step tasks.

### Technology Stack

| Component | Technology | Purpose |
|-----------|-----------|---------|
| Framework | FastAPI | High-performance async API server |
| Agent Framework | Deep Agents (0.3.12) | Agent orchestration and planning |
| Runtime | LangGraph | Durable execution, streaming, HITL |
| LLM | ChatLiteLLM | Flexible LLM integration (GitHub Copilot) |
| Integration | CopilotKit | Frontend-backend agent communication |
| Memory | MemorySaver | Conversation state persistence |

### Project Structure

```
backend/
├── src/
│   └── agent/
│       ├── main.py          # FastAPI app + CopilotKit integration
│       └── utils.py         # Agent builder + tools
├── tests/
│   └── agent/
│       └── test_main.py     # Unit tests
├── k8s/
│   └── deployment.yaml      # Kubernetes manifests
├── Dockerfile               # Container image
├── pyproject.toml           # Python dependencies
└── Makefile                 # Build and run commands
```

### Key Components

#### 1. Agent Builder ([utils.py](backend/src/agent/utils.py))

```python
from deepagents import create_deep_agent
from copilotkit import CopilotKitMiddleware

def build_agent():
    agent_graph = create_deep_agent(
        model=ChatLiteLLM(model="github_copilot/gpt-5-mini"),
        tools=[get_weather],
        middleware=[CopilotKitMiddleware()],
        system_prompt="You are a helpful assistant",
        checkpointer=MemorySaver(),
    )
    return agent_graph
```

**Deep Agents Features Used:**
- 🧠 **Model**: Flexible LLM integration via LiteLLM
- 🔧 **Tools**: Custom tool functions (get_weather)
- 🔌 **Middleware**: CopilotKit for streaming and UI updates
- 💾 **Checkpointer**: Conversation memory across sessions

#### 2. FastAPI Server ([main.py](backend/src/agent/main.py))

```python
from ag_ui_langgraph import add_langgraph_fastapi_endpoint
from copilotkit import LangGraphAGUIAgent

app = FastAPI()
agent_graph = build_agent()

add_langgraph_fastapi_endpoint(
    app=app,
    agent=LangGraphAGUIAgent(
        name="weather_application_assistant",
        graph=agent_graph,
    ),
    path="/",
)
```

The `LangGraphAGUIAgent` wraps the Deep Agents graph and exposes it via FastAPI endpoints that CopilotKit can connect to.

### Running the Backend

```bash
# Install dependencies
cd backend
uv sync

# Run locally
uv run python src/agent/main.py

# Run tests
uv run pytest

# Build Docker image
make build
```

The backend listens on `http://0.0.0.0:8123` and exposes:
- `/` - LangGraph agent endpoints
- `/healthz` - Health check endpoint

---

## ⚛️ Frontend - Next.js with CopilotKit Generative UI

The frontend is a Next.js application that uses **CopilotKit** to create beautiful generative UIs that respond to agent tool calls in real-time.

### Technology Stack

| Component | Technology | Purpose |
|-----------|-----------|---------|
| Framework | Next.js 16 | React framework with App Router |
| UI Library | CopilotKit (1.51.4) | Agent integration + generative UI |
| Styling | Tailwind CSS | Utility-first styling |
| Agent Client | LangGraphHttpAgent | HTTP client for backend connection |
| Language | TypeScript | Type-safe development |

### Project Structure

```
frontend/
├── src/
│   └── app/
│       ├── page.tsx              # Main page with generative UI
│       ├── layout.tsx            # App layout with CopilotKit provider
│       ├── globals.css           # Global styles
│       └── api/
│           └── copilotkit/
│               └── route.ts      # CopilotKit API endpoint
├── k8s/
│   └── deployment.yaml           # Kubernetes manifests
├── Dockerfile                    # Container image
├── package.json                  # Node dependencies
└── next.config.ts                # Next.js configuration
```

### Key Components

#### 1. CopilotKit Runtime ([route.ts](frontend/src/app/api/copilotkit/route.ts))

```typescript
import { CopilotRuntime } from "@copilotkit/runtime";
import { LangGraphHttpAgent } from "@copilotkit/runtime/langgraph";

const runtime = new CopilotRuntime({
  agents: {
    weather_assistant: new LangGraphHttpAgent({
      url: process.env.LANGGRAPH_DEPLOYMENT_URL || "http://localhost:8123",
    }),
  },
});
```

The `LangGraphHttpAgent` connects to the backend FastAPI server and streams tool calls and responses.

#### 2. Generative UI with `useRenderToolCall` ([page.tsx](frontend/src/app/page.tsx))

```tsx
import { useRenderToolCall } from "@copilotkit/react-core";

useRenderToolCall({
  name: "get_weather",
  render: ({status, args, result}) => {
    const weatherData = JSON.parse(result);
    
    return (
      
        {weatherData.location}
        {weatherData.temperature}°{weatherData.unit}
        {weatherData.weather}
      
    );
  }
});
```

**Generative UI Features:**
- 🎨 **Custom Rendering**: Fully customizable UI components
- ⚡ **Real-time Updates**: Status changes as tool executes
- 🔄 **Loading States**: Built-in loading animations
- 📊 **Rich Data Display**: Parse and display structured data

#### 3. Weather Card Component

The weather card demonstrates advanced generative UI features:
- Dynamic gradients based on weather conditions
- Weather icons (☀️, ☁️, 🌧️, ❄️, ⛈️)
- Animated loading states
- Responsive hover effects
- Real-time status indicators

### Running the Frontend

```bash
# Install dependencies
cd frontend
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm start
```

The frontend runs on `http://localhost:3000` and connects to the backend via the `LANGGRAPH_DEPLOYMENT_URL` environment variable.

---

## ☸️ Kubernetes & Skaffold Deployment

This project uses **Skaffold** for streamlined Kubernetes development with hot reloading and automatic rebuilds.

### Architecture

```mermaid
graph TB
    subgraph "Kubernetes Cluster"
        subgraph "Frontend Service"
            FP[Port 3000]
            FD[Deployment: frontend]
            FC[Container: Next.js]
            
            FP --> FD
            FD --> FC
        end
        
        subgraph "Backend Service"
            BP[Port 8123]
            BD[Deployment: backend]
            BC[Container: FastAPI]
            
            BP --> BD
            BD --> BC
        end
        
        FC --> |HTTP| BP
    end
    
    DEV[Developer] --> |skaffold dev| Skaffold
    Skaffold --> |Build Images| Docker
    Skaffold --> |Deploy| K8S[kubectl]
    K8S --> FD
    K8S --> BD
    Skaffold --> |Port Forward| FP
    DEV --> |http://localhost:3000| FP
    
    style FD fill:#61dafb
    style BD fill:#f59e0b
    style Skaffold fill:#0ea5e9
```

### Skaffold Configuration

The [skaffold.yaml](skaffold.yaml) file defines the build and deployment pipeline:

```yaml
build:
  artifacts:
    - image: frontend
      sync:
        infer:
          - "**/*.ts"
          - "**/*.tsx"
          - "**/*.css"
    
    - image: backend
      sync:
        infer:
          - "**/*.py"

manifests:
  rawYaml:
    - frontend/k8s/deployment.yaml
    - backend/k8s/deployment.yaml

portForward:
  - resourceType: service
    resourceName: frontend
    port: 3000
```

### Key Features

| Feature | Description |
|---------|-------------|
| **Hot Reload** | File sync for `.ts`, `.tsx`, `.py` files - no rebuild needed |
| **Auto Rebuild** | Automatic Docker image rebuild on code changes |
| **Port Forwarding** | Access frontend at `localhost:3000` |
| **Service Discovery** | Backend accessible at `http://backend:8123` from frontend |
| **Local Development** | Full Kubernetes environment on your machine |

### Kubernetes Resources

#### Backend Service ([backend/k8s/deployment.yaml](backend/k8s/deployment.yaml))

```yaml
apiVersion: v1
kind: Service
metadata:
  name: backend
spec:
  ports:
    - port: 8123
  selector:
    app: backend
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: backend
          image: backend
```

#### Frontend Service ([frontend/k8s/deployment.yaml](frontend/k8s/deployment.yaml))

```yaml
apiVersion: v1
kind: Service
metadata:
  name: frontend
spec:
  ports:
    - port: 3000
  selector:
    app: frontend
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: frontend
          image: frontend
          env:
            - name: LANGGRAPH_DEPLOYMENT_URL
              value: "http://backend:8123"
```

### Development Workflow

```bash
# Start development environment
skaffold dev

# This will:
# 1. Build Docker images for frontend and backend
# 2. Deploy to Kubernetes
# 3. Set up port forwarding
# 4. Watch for file changes and hot reload

# Access the application
open http://localhost:3000

# Clean up
# Press Ctrl+C to stop skaffold
# Resources are automatically deleted
```

### Production Deployment

For production, you would:
1. Build and push images to a container registry
2. Update image references in deployment manifests
3. Apply manifests to production cluster
4. Configure ingress for external access

```bash
# Build production images
docker build -t your-registry/backend:v1.0 ./backend
docker build -t your-registry/frontend:v1.0 ./frontend

# Push to registry
docker push your-registry/backend:v1.0
docker push your-registry/frontend:v1.0

# Deploy to production
kubectl apply -f backend/k8s/deployment.yaml
kubectl apply -f frontend/k8s/deployment.yaml
```

---

## 🚀 Getting Started

### Prerequisites

- **Python 3.13+** and `uv` for backend
- **Node.js 20+** and `npm` for frontend
- **Docker** for containerization
- **Local Kubernetes cluster** (Tested on [Minikube for Linux](https://minikube.sigs.k8s.io/docs/start/?arch=%2Flinux%2Fx86-64%2Fstable%2Fbinary+download) and [Docker Desktop Kubernetes for Mac](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes))
- **Skaffold CLI** for development workflow
- **API Keys**: GitHub Copilot or other LLM provider

### Quick Start

1. **Clone the repository**

```bash
git clone https://github.com/nsphung/agent-studio-starter.git
cd agent-studio-starter
```

2. **Start with Skaffold**

```bash
# Make sure Local Kubernetes is running (Minikube or Docker Desktop Kubernetes, etc...)
skaffold dev
```

3. **Access the application**

Open your browser to `http://localhost:3000` and start chatting!

Try asking:
- "What's the weather in San Francisco?"
- "Tell me the weather in Tokyo"
- "How's the weather in London?"

### Manual Setup (Without Skaffold)

#### Backend

```bash
cd backend
uv sync
uv run python src/agent/main.py
```

#### Frontend

```bash
cd frontend
npm install
npm run dev
```

---

## 📁 Project Structure

```
agent-studio-starter/
├── backend/                  # Python FastAPI backend
│   ├── src/agent/           # Agent code
│   ├── tests/               # Unit tests
│   ├── k8s/                 # Kubernetes manifests
│   ├── Dockerfile           # Container image
│   └── pyproject.toml       # Dependencies
│
├── frontend/                # Next.js frontend
│   ├── src/app/            # Next.js app
│   ├── k8s/                # Kubernetes manifests
│   ├── Dockerfile          # Container image
│   └── package.json        # Dependencies
│
├── notebooks/              # Jupyter notebooks for evaluation
│   └── evaluate.ipynb      # Agent evaluation
│
├── skaffold.yaml          # Skaffold configuration
├── Makefile               # Build commands
└── README.md              # This file
```

---

## 🎓 Learning Resources

### Lang

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nsphung](https://github.com/nsphung)
- **Source:** [nsphung/agent-studio-starter](https://github.com/nsphung/agent-studio-starter)
- **License:** Apache-2.0
- **Homepage:** https://www.linkedin.com/in/nsphung/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nsphung-agent-studio-starter
- Seller: https://agentstack.voostack.com/s/nsphung
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.