# base-agent

**Repository Path**: mirrors_microsoft/base-agent

## Basic Information

- **Project Name**: base-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-21
- **Last Updated**: 2025-11-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Base Agent

A RAG (Retrieval-Augmented Generation) agent powered by Azure OpenAI. Deploy your own AI assistant with custom knowledge bases in minutes.

## 🚀 Quick Start

### Using Pre-built Container (Recommended)

```bash
docker run -p 5175:80 \
  -e AZURE_ENDPOINT="https://your-resource.openai.azure.com" \
  -e AZURE_API_KEY="your-api-key" \
  -e AZURE_DEPLOYMENT="gpt-4o-mini" \
  -e AZURE_EMBEDDING_DEPLOYMENT="text-embedding-ada-002" \
  ghcr.io/microsoft/base-agent:latest
```

Then open http://localhost:5175 in your browser.

### Using Docker Compose

```bash
# Copy environment template
cp .env.example .env
# Edit .env with your Azure OpenAI credentials

# Start the agent
docker compose up -d

# View logs
docker compose logs -f
```

### Configuration Required

You'll need an Azure OpenAI resource with:
- **Endpoint URL**: Your Azure OpenAI service endpoint
- **API Key**: Your access key
- **Chat Model**: A chat model deployment (GPT-4o-mini recommended)
- **Embedding Model**: An embedding model deployment (text-embedding-ada-002 recommended)

## ✨ Features

- 🧠 **Smart RAG System**: Import embeddings and get contextual AI responses
- 📊 **Source Management**: Weight and toggle different knowledge sources  
- 💬 **Natural Conversations**: Persistent chat history with source citations
- 🔧 **Easy Configuration**: Web-based setup with environment variable support
- 🐳 **Container Ready**: One-command deployment with Docker/Podman
- 📱 **Responsive UI**: Clean interface that works on desktop and mobile
- 📦 **Agent Packs**: Pre-configured knowledge bases for instant deployment
- ☁️ **Azure Ready**: ARM/Bicep templates for Azure Container Instances

## 📥 Creating Embeddings

Generate embeddings from your documentation using the [Microsoft Embeddings Tool](https://github.com/microsoft/embeddings-tool):

```bash
# Install
pip install embeddings-tool

# Generate embeddings from your docs
embeddings-tool --input ./docs --output embeddings_docs.json
```

The tool supports multiple formats (PDF, DOCX, PPTX, Markdown) and produces JSON files ready to import into your agent pack.

## 📚 Documentation

### Getting Started
- [Product Requirements](PRD.md) - Complete feature documentation
- [Agent Pack Format](docs/agent-pack-format.md) - Specification for agent packages
- [Building Custom Agents](docs/derived-agent-example.md) - Create specialized agents

### Deployment
- [Azure Deployment](azure/README.md) - Deploy to Azure Container Instances
- [Docker Compose](docker-compose.yml) - Local development setup
- [Environment Variables](#-environment-variables) - Configuration reference

## 🏗️ Container Images

Images are automatically built and published on every commit:

- `ghcr.io/microsoft/base-agent:latest` - Latest stable version
- `ghcr.io/microsoft/base-agent:v*.*.*` - Specific version tags
- Multi-platform support (linux/amd64, linux/arm64)

## 🔐 Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AZURE_ENDPOINT` | Your Azure OpenAI endpoint URL | Required |
| `AZURE_API_KEY` | Your Azure OpenAI API key | Required |
| `AZURE_DEPLOYMENT` | Chat model deployment name | `gpt-4o-mini` |
| `AZURE_EMBEDDING_DEPLOYMENT` | Embedding model deployment name | `text-embedding-ada-002` |
| `AZURE_API_VERSION` | Azure OpenAI API version | `2024-02-15-preview` |
| `AGENT_PACK_PATH` | Path to pre-loaded agent pack | `/agent-pack.zip` |

## 🎯 Use Cases

### 1. Base Agent (Manual Configuration)
Start with an empty agent and import your own embeddings:
```bash
docker run -p 5175:80 \
  -e AZURE_ENDPOINT="..." \
  -e AZURE_API_KEY="..." \
  ghcr.io/microsoft/base-agent:latest
```

### 2. Custom Agent with Volume Mount
Use the base image with your pre-built agent pack:
```bash
docker run -p 5175:80 \
  -v ./my-agent-pack.zip:/app/agent-pack.zip:ro \
  -v ./agent-config.json:/app/agent-config.json:ro \
  -e AZURE_ENDPOINT="..." \
  -e AZURE_API_KEY="..." \
  ghcr.io/microsoft/base-agent:latest
```

### 3. Derived Agent Image
Build a custom image with embedded agent pack:
```dockerfile
FROM ghcr.io/microsoft/base-agent:latest
COPY agent-pack.zip /app/agent-pack.zip
COPY agent-config.json /app/agent-config.json
```

See [docs/derived-agent-example.md](docs/derived-agent-example.md) for complete examples.

## 🏥 Health Check

The agent includes a health check endpoint at `/health.html`:

```bash
curl http://localhost:5175/health.html
```

This page shows:
- Number of chunks loaded
- Source count
- Configuration status
- Pack loading status

## 🛠️ Local Development

```bash
# Clone and install
git clone https://github.com/microsoft/base-agent.git
cd base-agent
npm install

# Start development server
npm run dev
```

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.