OCI AI Agent UI

October 31, 2025 · View on GitHub

A modern web interface for interacting with OCI AI agents, built with Next.js and FastAPI.

Frameworks:

OCI Agent Development Kit (ADK): setting up and modifying OCI AI Agent Service
AG-UI: an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications.
CopilotKit: an easy way to add AI copilots - intelligent, context-aware assistants - into your app.
Next.js: a React framework for building server-rendered and static web applications.
FastAPI: a modern, fast (high-performance), web framework for building APIs with Python.

Note: The main purpose of this project is to test OCI AI Agent through a neat web interface. Current version is only for testing and development purpose. It should be modified for production use.

🚀 Quick Start

Frontend Setup

Install dependencies:
```
cd frontend
npm install
```
Start the development server:
```
npm run dev:ui
```
The frontend will be available at http://localhost:3000

Backend Setup

Set up environment variables:
```
cp backend/src/.env.example backend/src/.env
```
Update the environment variables in backend/src/.env with your own values.
Install dependencies using uv (no virtual environment needed):
```
cd backend
uv pip install -r requirements.txt
```
Start the backend server with hot reload:
```
uv run src/main.py
```
The API will be available at http://localhost:8008

Screen Shots

RAG Agent

Single Function Tool Agent

Multiple Function Tool Agent

Advanced Setup

How it works

When you send a message to the agent, the backend will response with a stream of events, including agent's traces(planning, tool invocations, etc.) and answer message.

The frontend uses CopilotKit to interact with the backend.

The frontend and backend are connected through AG-UI protocol. The frontend sends a message to the backend, and the backend sends a response to the frontend. The response is a stream of events, which are processed by the frontend and displayed in the UI.

The backend uses OCI Python SDK to interact with OCI AI Agent Service, which is setting through OCI Agent Development Kit.

Every time the front page refreshes, a new agent session is created in the backend. The session ID is passed to the backend through the AG-UI protocol.

Setting up OCI AI Agent service

You can find the documentation for setting up OCI AI Agent service through OCI Agent Development Kit.

An example is provided in the backend/src/adk_rag&tool.py file.

Frontend-Backend Connection

By default, the frontend connects to the backend at http://localhost:8008. To change this:

Update the agent URL in frontend/src/app/api/copilotkit/route.ts:

const runtime = new CopilotRuntime({
  agents: {
    "my_agent": new HttpAgent({url: "YOUR_BACKEND_URL"}),
  }   
});

Ensure the agent name matches in frontend/src/app/page.tsx:

<CopilotKit agent="my_agent">
  <Chat />
</CopilotKit>

📦 Project Structure

.
├── frontend/         # Next.js frontend application
├── backend/          # FastAPI backend service
│   ├── src/          # Source code
└── README.md         # This file

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.