# maf-with-copilotkit-sample

**Repository Path**: jiahengaa/maf-with-copilotkit-sample

## Basic Information

- **Project Name**: maf-with-copilotkit-sample
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CopilotKit <> Microsoft Agent Framework Starter

This starter pairs a minimal [Hono](https://hono.dev/) backend with a Vite React frontend and a C# Microsoft Agent Framework agent. It demonstrates AG-UI protocol features including generative UI, human-in-the-loop workflows, frontend actions, and CopilotKit Intelligence threads.

## Prerequisites

- **OpenAI API key**
  - Create an API key from the [OpenAI dashboard](https://platform.openai.com/api-keys).
- **.NET 9.0 SDK**
  - [Download directly](https://dotnet.microsoft.com/download/dotnet/9.0), install with Homebrew (`brew install dotnet@9`), or install with WinGet (`winget install --id=Microsoft.DotNet.SDK.9 -e`).
- **Node.js 20+**
  - [Download directly](https://nodejs.org/en/download), install with Homebrew (`brew install node@24`), or install with WinGet (`winget install --id=OpenJS.NodeJS -e`).

## Getting Started

1. Install dependencies:

   ```bash
   npm install
   ```

   This also restores NuGet packages for the C# agent. If you need to run that step manually:

   ```bash
   npm run install:agent
   ```

2. Set up your OpenAI API key:

   ```bash
   cd agent
   dotnet user-secrets set OpenAIApiKey "<your-api-key>"
   cd ..
   ```

   Or export it before starting the agent:

   ```bash
   export OPENAI_API_KEY="<your-api-key>"
   ```

3. Start the development stack:

   ```bash
   npm run dev
   ```

   This starts the Vite UI on port `3000`, the Hono API server on port `3001`, and the C# agent on port `8000`. Vite proxies `/api/*` to Hono, so the browser uses a single origin at `http://localhost:3000`.

## Available Scripts

- `dev` - Starts local intelligence infra, Hono, Vite, and the C# agent.
- `dev:debug` - Starts the development stack with `LOG_LEVEL=debug`.
- `dev:server` - Starts only the Hono server on port `3001`.
- `dev:ui` - Starts only the Vite frontend on port `3000`.
- `dev:agent` - Starts only the C# agent server.
- `build` - Type-checks, builds the Vite frontend, and compiles the Hono server.
- `start` - Runs the compiled Hono server, which serves the built Vite assets and `/api/copilotkit`.
- `lint` - Runs TypeScript checking.
- `install:agent` - Restores NuGet packages for the C# agent.

## Project Structure

```text
├── agent/                  # C# agent (Microsoft Agent Framework)
├── src/
│   ├── App.tsx             # React app and CopilotKit demo wiring
│   ├── main.tsx            # Vite React entrypoint and CopilotKit provider
│   ├── server.ts           # Minimal Hono backend and CopilotKit runtime route
│   ├── components/         # UI components
│   └── lib/                # Shared frontend types and utilities
├── index.html              # Vite HTML entrypoint
├── vite.config.ts          # Vite dev server, proxy, and aliases
└── scripts/                # Helper scripts for agent setup/run
```

## CopilotKit Intelligence

Threads are enabled when `COPILOTKIT_LICENSE_TOKEN` is present before running `npm run dev` or `npm run build`. The Hono server reads that token for the runtime, and `vite.config.ts` derives `VITE_COPILOTKIT_THREADS_ENABLED=true` for the frontend gate.

Optional local intelligence services can be started with:

```bash
docker compose up -d --wait
```

## Troubleshooting

### Agent Connection Issues

If the assistant cannot connect to its tools, check that:

1. The C# agent is running on port `8000`.
2. `AGENT_URL` points at that agent, defaulting to `http://localhost:8000/`.
3. Your OpenAI API key is set through user secrets or `OPENAI_API_KEY`.
4. Hono is running on port `3001` in development.

### Port Conflicts

Use these environment variables to move local ports:

```bash
SERVER_PORT=3002 VITE_PORT=3000 npm run dev
```

If you change the C# agent port, update `AGENT_URL`:

```bash
AGENT_URL=http://localhost:8010 npm run dev
```

### Production Build

```bash
npm run build
npm start
```

The production server listens on `PORT` or `3000` by default.

## Documentation

- [Microsoft Agent Framework](https://github.com/microsoft/agents)
- [AG-UI Protocol](https://github.com/copilotkit/ag-ui)
- [CopilotKit Documentation](https://docs.copilotkit.ai)
- [Hono Documentation](https://hono.dev/)
- [Vite Documentation](https://vite.dev/)
- [OpenAI API Documentation](https://platform.openai.com/docs)