ACONTEXT Agent Playground

A production-ready starter template for building context-aware, autonomous AI agents

Features · Getting Started · Deployment · Documentation

ACONTEXT Agent Playground is a production-ready starter template for building context-aware, autonomous AI agents powered by Acontext. This template provides a complete foundation with authentication, chat interface, tool integration, and session management, allowing you to quickly build and customize your own AI agent applications.

🚀 What is This?

This is a start template that inherits the powerful capabilities of the Acontext platform, including:

Session Management: Persistent conversation sessions with automatic context management
Semantic Search: Intelligent retrieval of relevant conversation history
File & Artifact Management: Upload, store, and manage files through Acontext Disk
Experience Learning: Search and reuse learned skills from user Spaces
Context Compression: Automatic token management and context optimization
Tool Integration: Extensible tool system for custom functionality

✨ Features

Core Capabilities

🔐 Authentication: Email/password authentication with Supabase
💬 Chat Interface: Full-featured chat UI with message history, streaming responses, and tool call visualization
🎨 Customizable UI: Built with Tailwind CSS and shadcn/ui components - fully customizable
🤖 Avatar Support: Easy to customize agent avatar and branding
🛠️ Extensible Tools: Add your own custom tools or modify existing ones
📁 File Upload: Support for uploading PDFs, images, and documents
🌐 Browser Automation: Integrated Browser Use SDK for web automation tasks
🌓 Theme Support: Dark/light mode with next-themes

Acontext Integration

Session Persistence: Each chat session maps to an Acontext Session
Semantic Context Search: Automatically retrieves relevant historical context before generating responses
Disk Storage: Files are stored in Acontext Disk with automatic tool access
Experience Search: Leverages learned skills from user Spaces to improve responses
Context Compression: Automatic token management with manual compression option

🛠️ Tech Stack

Framework: Next.js 15+ (App Router)
Authentication & Database: Supabase (@supabase/supabase-js, @supabase/ssr)
AI Platform: Acontext (@acontext/acontext)
LLM: OpenAI (openai SDK) - compatible with OpenAI API
Browser Agent: Browser Use SDK (browser-use-sdk)
UI Components: Tailwind CSS, shadcn/ui, Lucide icons
Language: TypeScript
Theming: next-themes

📦 Getting Started

Prerequisites

Node.js 18+ and npm/yarn/pnpm
A Supabase account (create one here)
An Acontext account (sign up here)
An OpenAI API key (or compatible API endpoint)

Installation

Clone the repository

git clone <your-repo-url> nextjs-with-supabase-acontext
cd nextjs-with-supabase-acontext

Install dependencies

npm install
# or
yarn install
# or
pnpm install

Set up Supabase
- Create a new project at Supabase Dashboard
- Note your Project URL and Anon (publishable) key
Configure environment variables

Create a .env.local file in the root directory:

# Supabase (required)
NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-supabase-publishable-or-anon-key

# Acontext (required for full functionality)
ACONTEXT_API_KEY=your-acontext-api-key
ACONTEXT_BASE_URL=https://api.acontext.com/api/v1  # Optional, defaults to this

# OpenAI LLM (required)
OPENAI_LLM_ENDPOINT=https://api.openai.com/v1
OPENAI_LLM_API_KEY=your-openai-api-key
OPENAI_LLM_MODEL=gpt-4o-mini  # or gpt-3.5-turbo, gpt-4, etc.
OPENAI_LLM_TEMPERATURE=0.7
OPENAI_LLM_MAX_TOKENS=2000

# Browser Use Cloud (optional, for browser automation)
BROWSER_USE_API_KEY=your-browser-use-cloud-api-key

Set up database schema
- Open your Supabase project
- Go to SQL Editor
- Run the SQL from specs/001-chatbot-openai/schema.sql
- This creates tables for chat_sessions and chat_messages
- For Acontext integration, also run specs/001-chatbot-openai/migration-acontext.sql
Run the development server

npm run dev
# or
yarn dev
# or
pnpm dev

Visit http://localhost:3000 to see your application.

🎨 Customization Guide

Customizing the UI

The UI is built with Tailwind CSS and shadcn/ui components, making it easy to customize:

Theme Colors: Edit tailwind.config.ts to change color schemes
Components: All UI components are in components/ui/ - modify as needed
Layout: Main pages are in app/ directory
Homepage: Customize app/page.tsx for your landing page
Chat Interface: Modify components/chatbot-panel.tsx for chat UI changes

Customizing the Avatar

The agent avatar can be customized in several ways:

Character Image: Replace components/parallax-character.tsx with your own character/logo
Homepage Avatar: Update the parallax character component or homepage hero section
Chat Avatar: Modify the avatar display in components/chatbot-panel.tsx

Example locations:

components/parallax-character.tsx - Homepage parallax character
public/acontext-character.png - Character assets
app/page.tsx - Homepage layout

Adding Custom Tools

Tools are defined as OpenAI function calling schemas. To add your own tool:

Create a tool file in lib/ (e.g., lib/my-custom-tool.ts):

export function getMyToolSchema() {
  return {
    type: "function" as const,
    function: {
      name: "my_custom_tool",
      description: "Description of what your tool does",
      parameters: {
        type: "object",
        properties: {
          param1: {
            type: "string",
            description: "Parameter description",
          },
        },
        required: ["param1"],
      },
    },
  };
}

export async function executeMyTool(args: { param1: string }) {
  // Your tool logic here
  return {
    result: "Tool execution result",
  };
}

Register the tool in lib/openai-client.ts:

// Add to getAvailableTools function
if (shouldIncludeMyTool) {
  tools.push(getMyToolSchema());
}

// Add to executeToolCall function
if (name === "my_custom_tool") {
  const args = JSON.parse(argsJson || "{}");
  return await executeMyTool(args);
}

Wire it into the chat API in app/api/chatbot/route.ts:

// The tools are automatically included when calling chatCompletionStream

Existing Tool Examples:

lib/browser-use.ts - Browser automation
lib/acontext-disk-tools.ts - File system operations
lib/acontext-experience-search-tool.ts - Experience search
lib/acontext-todo-tool.ts - Todo management

Customizing Acontext Integration

The Acontext integration is modular and can be customized:

Session Management: lib/acontext-integration.ts - Modify session creation and management
Client Configuration: lib/acontext-client.ts - Adjust Acontext client settings
Tool Integration: lib/acontext-disk-tools.ts - Customize disk tool behavior
Experience Search: lib/acontext-experience-search-tool.ts - Modify search logic

📚 Project Structure

nextjs-with-supabase-acontext/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   │   ├── acontext/      # Acontext API endpoints
│   │   ├── chatbot/       # Chat API endpoint
│   │   └── tools/         # Tools API endpoint
│   ├── auth/              # Authentication pages
│   ├── protected/         # Protected chat page
│   └── page.tsx           # Homepage
├── components/             # React components
│   ├── ui/                # shadcn/ui components
│   ├── chatbot-panel.tsx  # Main chat interface
│   └── parallax-character.tsx  # Homepage character
├── lib/                   # Core libraries
│   ├── acontext-*.ts      # Acontext integration
│   ├── openai-client.ts   # OpenAI client wrapper
│   ├── browser-use.ts    # Browser automation
│   └── supabase/          # Supabase utilities
├── specs/                 # Project specifications
└── types/                 # TypeScript types

🔧 Available Tools

Built-in Tools

Browser Use Task (browser_use_task)
- Performs web automation tasks
- Requires Browser Use Cloud API key
- Location: lib/browser-use.ts
Acontext Disk Tools
- write_file, read_file, replace_string, list_artifacts, download_file
- File system operations on Acontext Disk
- Location: lib/acontext-disk-tools.ts
Experience Search (experience_search)
- Searches user's learned skills from Acontext Space
- Location: lib/acontext-experience-search-tool.ts
Todo Management (todo)
- Create and manage todos within chat sessions
- Location: lib/acontext-todo-tool.ts

Adding Your Own Tools

See the Customization Guide section above.

🌐 Environment Variables

Variable	Description	Required
`NEXT_PUBLIC_SUPABASE_URL`	Supabase project URL	Yes
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	Supabase publishable/anon key	Yes
`ACONTEXT_API_KEY`	Acontext API key	Yes (for full features)
`ACONTEXT_BASE_URL`	Acontext API base URL	No (has default)
`OPENAI_LLM_ENDPOINT`	OpenAI-compatible API endpoint	Yes
`OPENAI_LLM_API_KEY`	OpenAI API key	Yes
`OPENAI_LLM_MODEL`	Model name (e.g., `gpt-4o-mini`)	Yes
`OPENAI_LLM_TEMPERATURE`	Temperature (0-2)	No (default: 0.7)
`OPENAI_LLM_MAX_TOKENS`	Max tokens in response	No (default: 2000)
`BROWSER_USE_API_KEY`	Browser Use Cloud API key	No (optional)
`IMAGE_GEN_API_KEY`	Upstream image generation API key (sent as `x-goog-api-key`)	No (optional, required for image_generate)
`IMAGE_GEN_BASE_URL`	Upstream image generation base URL	No (default: `https://api.openai-next.com`)
`IMAGE_GEN_DEFAULT_MODEL`	Image generation model name (server-controlled; not overridable by tool args)	No (default: `gemini-3-pro-image-preview`)

🚢 Deployment

Deploy to Vercel

Vercel deployment will guide you through creating a Supabase account and project.

After installation of the Supabase integration, all relevant environment variables will be assigned to the project so the deployment is fully functioning.

The above will also clone the Starter kit to your GitHub, you can clone that locally and develop locally.

Vercel Configuration Explained

When deploying to Vercel, you have two options:

Option 1: One-Click Deploy (Recommended for First-Time Setup)

Click the "Deploy with Vercel" button above
Vercel will prompt you to:
- Sign in to Vercel (or create an account)
- Connect your GitHub account (if not already connected)
- Create a new Supabase project (or connect existing one)
During the Supabase integration setup:
- Vercel will automatically create a Supabase project for you
- All required Supabase environment variables will be automatically configured:
  - NEXT_PUBLIC_SUPABASE_URL
  - NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
You'll need to manually add the remaining environment variables in Vercel dashboard:
- ACONTEXT_API_KEY - Your Acontext API key
- OPENAI_LLM_ENDPOINT - OpenAI API endpoint (default: https://api.openai.com/v1)
- OPENAI_LLM_API_KEY - Your OpenAI API key
- OPENAI_LLM_MODEL - Model name (e.g., gpt-4o-mini)
- OPENAI_LLM_TEMPERATURE - Temperature (default: 0.7)
- OPENAI_LLM_MAX_TOKENS - Max tokens (default: 2000)
- BROWSER_USE_API_KEY - Optional, for browser automation
- ACONTEXT_BASE_URL - Optional, defaults to https://api.acontext.com/api/v1
After deployment, run the database migrations:
- Go to your Supabase project dashboard
- Navigate to SQL Editor
- Run the SQL from specs/001-chatbot-openai/schema.sql
- Run the SQL from specs/001-chatbot-openai/migration-acontext.sql

Option 2: Manual Deployment (If You Already Have a GitHub Repository)

Push your code to GitHub
Go to Vercel Dashboard
Click "Add New Project"
Import your GitHub repository
Configure environment variables:
- Supabase Integration: Click "Add Integration" → Search "Supabase" → Connect your Supabase project
  - This automatically sets NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
- Manual Variables: Add the remaining environment variables listed above
Click "Deploy"
After deployment, run the database migrations in Supabase SQL Editor

Environment Variables in Vercel

To add environment variables in Vercel:

Go to your project in Vercel Dashboard
Navigate to Settings → Environment Variables
Add each variable with its value
Select which environments to apply to (Production, Preview, Development)
Click "Save"
Redeploy your application for changes to take effect

Important Notes:

Environment variables starting with NEXT_PUBLIC_ are exposed to the browser
Keep sensitive keys (like OPENAI_LLM_API_KEY, ACONTEXT_API_KEY) secure and never commit them
Vercel automatically provides NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY when you use the Supabase integration

Local Development After Vercel Deployment

If you wish to just develop locally and not deploy to Vercel, follow the steps below:

Clone the repository from GitHub (created during Vercel deployment)
Install dependencies: npm install
Create .env.local file with all environment variables (see Installation section)
Run database migrations in Supabase SQL Editor
Start development server: npm run dev

Other Platforms

This is a standard Next.js application and can be deployed to any platform that supports Next.js:

Netlify
Railway
Render
AWS Amplify
Self-hosted with Node.js

🔌 Acontext Integration Details

Implemented Features

1. Session Persistence ✅

Each chat session maps to an Acontext Session (reused, not recreated each time)
Database schema includes acontext_session_id field
Sessions automatically create or reuse Acontext sessions
All messages are stored in the same Acontext session

2. Semantic Search ✅

Retrieves relevant historical context from Acontext before generating responses
Searches Acontext session for relevant historical messages before calling LLM
Injects search results into system prompt to enhance context coherence
Enabled by default, can be disabled with enableSemanticSearch: false

3. File Upload & Artifacts ✅

Support for uploading files (PDFs, images, documents) for AI analysis
Chat interface includes file upload button (📎 icon)
Supports multiple file uploads
Files are uploaded to Acontext Disk via Artifacts API
Uploaded files are referenced in messages, AI can read file content
Image Support: Uses OpenAI Vision API, AI can directly view and analyze images
File List View: View all files stored in Acontext Disk

4. File System Tools (Function Calling) ✅

LLM can autonomously read/write files on Acontext Disk through tool functions
Includes official DISK_TOOLS exposed via OpenAI Tool Schema: write_file, read_file, replace_string, list_artifacts, download_file
Chat API automatically provides these tools when Acontext is configured
Tools automatically select existing disk (or create one if needed), no frontend intervention required

File Upload Usage

Frontend (Chat Interface)

Click attachment button: 📎 (paperclip) icon button next to input box
Select files: Opens file picker, supports multiple files
View preview: Selected files appear above input box with filename
Remove attachment: Click ❌ button next to file to remove
Send message: Enter message and send, files upload with message
View file list: Click "Files" button to view all files in Acontext Disk

API Usage

Send a message with attachments:

const response = await fetch("/api/chatbot", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Analyze this document",
    sessionId: "your-session-id",
    attachments: [
      {
        filename: "document.pdf",
        content: "base64-encoded-content", // base64 encoded file content
        mimeType: "application/pdf",
      },
      {
        filename: "image.png",
        content: "base64-encoded-image",
        mimeType: "image/png",
      },
    ],
    enableSemanticSearch: true, // optional, default true
  }),
});

Attachment Format:

filename (string): File name
content (string): Base64 encoded file content (without data:image/png;base64, prefix)
mimeType (string): MIME type, e.g., application/pdf, image/png, text/plain

View File List

// List all artifacts
const response = await fetch("/api/acontext/artifacts");
const data = await response.json();

if (data.success) {
  console.log(`Found ${data.count} files:`, data.artifacts);
}

// List files from specific disk
const response = await fetch("/api/acontext/artifacts?diskId=your-disk-id");

Database Migration

Run the following SQL to add Acontext-related fields:

-- Run in Supabase SQL Editor
-- File location: specs/001-chatbot-openai/migration-acontext.sql

Environment Variables

Ensure Acontext is configured in .env.local:

ACONTEXT_API_KEY=your_api_key_here
ACONTEXT_BASE_URL=https://api.acontext.com/api/v1  # Optional, defaults to this

# Bypass proxy for Acontext API (local development only)
# When set to true or 1, Acontext API requests bypass HTTP_PROXY/HTTPS_PROXY
# Other service requests still use proxy
ACONTEXT_BYPASS_PROXY=true  # Optional, only needed for local development

Implementation Details

Key Files:

lib/acontext-integration.ts - Acontext integration utility functions
lib/acontext-disk-tools.ts - Acontext disk file system tools (Function Calling)
app/api/chatbot/route.ts - Updated chat API with Acontext integration
components/chatbot-panel.tsx - File upload UI
types/chat.ts - Updated type definitions

Key Functions:

getOrCreateAcontextSession() - Get or create Acontext session
searchRelevantContext() - Semantic search for relevant context
uploadFileToAcontext() - Upload file to Acontext
storeMessageInAcontext() - Store message in Acontext

Notes:

Optional Integration: If ACONTEXT_API_KEY is not configured, all Acontext features automatically skip, basic chat functionality remains unaffected
Error Handling: All Acontext operations have error handling, failures don't affect main flow
Performance: Semantic search retrieves recent messages as context, production may need more refined search strategy

📖 Documentation

🤝 Contributing

This is a starter template - feel free to fork and customize it for your needs!

📄 License

Check the LICENSE file in the repository.

🆘 Support

Acontext: Documentation | Support
Issues: Open an issue in the repository

Built with ❤️ using Acontext Platform

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.specstory		.specstory
app		app
components		components
docs		docs
lib		lib
specs/001-chatbot-openai		specs/001-chatbot-openai
types		types
.cursorindexingignore		.cursorindexingignore
.eslintignore		.eslintignore
.gitignore		.gitignore
.prettierignore		.prettierignore
README-zh.md		README-zh.md
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

ACONTEXT Agent Playground

🚀 What is This?

✨ Features

Core Capabilities

Acontext Integration

🛠️ Tech Stack

📦 Getting Started

Prerequisites

Installation

🎨 Customization Guide

Customizing the UI

Customizing the Avatar

Adding Custom Tools

Customizing Acontext Integration

📚 Project Structure

🔧 Available Tools

Built-in Tools

Adding Your Own Tools

🌐 Environment Variables

🚢 Deployment

Deploy to Vercel

Vercel Configuration Explained

Environment Variables in Vercel

Local Development After Vercel Deployment

Other Platforms

🔌 Acontext Integration Details

Implemented Features

1. Session Persistence ✅

2. Semantic Search ✅

3. File Upload & Artifacts ✅

4. File System Tools (Function Calling) ✅

File Upload Usage

Frontend (Chat Interface)

API Usage

View File List

Database Migration

Environment Variables

Implementation Details

📖 Documentation

🤝 Contributing

📄 License

🆘 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages