Skip to content

Home

Jump to bottom
souvik roy edited this page Apr 24, 2026 · 1 revision

OpenAgent Wiki

Welcome to the OpenAgent wiki — the companion to the main repository. OpenAgent is an open reference pipeline for AI agents that think before they act: a typed, five-stage flow from raw user text to streamed execution, built by OpenGraph.tech.

What you get

  • Five stages with Pydantic contracts between each: Intent → Ambiguity → Clarifier → Planner → (optional Context) → Executor.
  • Streaming pipeline and UI-friendly WebSocket updates.
  • Graceful degradation when optional services (web search, Redis, RAG, blob storage, auth) are not configured.

Wiki map

Page Description
Quickstart Clone, install, run, open the UI
Configuration Environment variables and optional providers
Pipeline Stages, schemas, orchestration, where to read code
Development Docker, layout, logging, contributing pointers
API-overview REST and WebSocket at a glance

Outside the wiki

If this wiki lives only in the main repo under wiki/, see Publishing-this-wiki to copy it to GitHub’s Wiki tab.

Development

Layout (high level)

OpenAgent/
├── backend/           # FastAPI app, agents, orchestrator, services
│   ├── agents/
│   ├── api/           # REST + WebSocket handlers
│   ├── models/
│   ├── orchestrator/
│   ├── prompts/
│   └── services/
├── frontend/          # Primary UI served at /static (when present)
├── public/            # Static assets / alternate static tree
├── api/               # e.g. Vercel serverless entry
├── run.py             # uvicorn entry (dev)
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
└── vercel.json

Run in dev

python run.py

Uvicorn runs backend.main:app with reload enabled from run.py.

Tests & quality

Use whatever the repo documents in CONTRIBUTING.md (if present). Before a PR, smoke-test with python run.py and exercise the main chat flow.

Docker

docker compose up

Adjust compose/env for your keys.

Vercel / serverless

The repo may include vercel.json and api/ for serverless deployment patterns. Treat as optional; local run.py is the reference dev path.

Logging

Root logging is configured in backend/main.py so backend.* loggers emit at INFO. Tune with LOG_LEVEL in .env.

Contributing

See the repository CONTRIBUTING.md and GitHub Issues. Small, stage-scoped changes are easier to review than cross-cutting refactors.

Configuration

All variables are documented in the repo’s .env.example. Copy it to .env and fill in what you need. Never commit .env — it is gitignored.

Required for core behavior

Variable Purpose
LLM_API_KEY Bearer token for your OpenAI-compatible API

LLM tuning

Variable Default / notes
LLM_BASE_URL https://api.openai.com/v1
LLM_MODEL gpt-4o
MAX_TOKENS 4096

Optional: web search (Clarifier auto-resolve)

Variable Purpose
EXA_API_KEY Exa search for the Clarifier stage. If missing, web-assisted auto-resolve is skipped.

Optional: caching

Variable Purpose
UPSTASH_REDIS_REST_URL Upstash Redis REST URL
UPSTASH_REDIS_REST_TOKEN Upstash token

If unset, the app uses in-memory caching where applicable.

Optional: RAG (PageIndex)

Variable Purpose
PAGEINDEX_API_KEY PageIndex for retrieval-augmented context

Additional KB-related settings may appear in backend/config.py (e.g. KNOWLEDGE_BASE_URL, paths). If PageIndex is not configured, KB bootstrap and RAG paths are skipped.

Optional: artifacts / blob

Variable Purpose
BLOB_READ_WRITE_TOKEN Vercel Blob for artifact storage when integrated

Optional: auth

Variable Purpose
SUPABASE_URL Supabase project URL
SUPABASE_ANON_KEY Supabase anonymous key

Server

Variable Default
HOST 0.0.0.0
PORT 8000
LOG_LEVEL INFO

Design principle

Missing keys are not hard errors for optional capabilities. The pipeline is built to degrade: no Exa → skip web; no Redis → memory; no PageIndex → no RAG from that source. Only the LLM path is required for the core demo loop.

API overview

The server is a FastAPI application (backend/main.py) with CORS enabled broadly for local/dev use — tighten for production behind your gateway.

REST

Routers are mounted from backend/api/rest.py (rest_router). Typical areas include:

  • Health / meta endpoints (as defined in the router)
  • Session or artifact routes wired to pipeline, cache_service, artifact_service, etc.

For the exact path list, open backend/api/rest.py or run the app and visit /docs (Swagger UI) or /redoc.

WebSocket

  • Path: /ws
  • Handler: backend/api/websocket.py → websocket_endpoint(websocket, pipeline)

Clients connect here for streaming pipeline events (phase updates, tokens, clarification prompts). Authentication may be enforced via auth_service when Supabase is configured — see the websocket module for the current handshake rules.

Static files

  • /static/... — frontend/ directory when it exists (CSS, JS, HTML under static mount).
  • GET / — May return frontend/index.html when the frontend directory is present.
  • GET /login.html, GET /auth — Login / auth HTML aliases.

Exact behavior depends on which directories exist on disk in your checkout or container image.

OpenAPI

Interactive docs (when the server is running):

Use these as the live contract when in doubt.

Home

Guides

Maintainers

Pipeline & architecture

OpenAgent runs a linear typed pipeline with optional branching for human clarification. Data between stages is Pydantic models (see backend/models/schemas.py).

Stages (in order)

  1. Intent — Raw user string → structured IntentSchema (goal, constraints, success criteria, alternatives, confidence).
  2. Ambiguity — IntentSchema → AmbiguityReport (what is still unknown; severity flags).
  3. Clarifier — AmbiguityReport → ClarifiedIntent. Uses optional web search to auto-fill answers; may pause for user answers for what cannot be resolved automatically.
  4. Planner — ClarifiedIntent → ExecutionPlan (numbered steps, dependencies, validation hints).
  5. Context (optional but important) — Reads the full plan and gathers KB/web/dependency context per step in parallel → enriches execution inputs.
  6. Executor — Runs steps in topological order, streams tokens, then assembles a final result with checks and trace_to_goal.

Orchestration

  • File to read first: backend/orchestrator/pipeline.py — wires agents, handles pause/resume around clarification (SessionState, resume_after_clarification).
  • Schemas: backend/models/schemas.py — single source of truth for cross-stage contracts.
  • Enums: backend/models/enums.py.

Agent modules

Stage Module
Intent backend/agents/intent_agent.py
Ambiguity backend/agents/ambiguity_agent.py
Clarifier backend/agents/clarification_agent.py
Planner backend/agents/planning_agent.py
Context backend/agents/context_agent.py
Executor backend/agents/execution_agent.py

Suggested reading order (from README)

  1. backend/models/schemas.py
  2. backend/agents/intent_agent.py
  3. backend/agents/clarification_agent.py
  4. backend/orchestrator/pipeline.py
  5. backend/agents/execution_agent.py

Streaming

Agents accept streaming callbacks (on_stream) so the WebSocket layer can forward partial output to the UI without blocking on full completion.

Recipes (short)

  • Cache intent, not the full final answer (clarifications change the path).
  • Keep control flow in Python; let the LLM fill structured content, not decide global branching ad hoc.
  • Parallelize retrieval in the context stage where possible (asyncio.gather).

More detail and pitfalls: see the main README on the repo.

Publishing this wiki to GitHub

GitHub’s Wiki tab uses a separate Git repository, not the wiki/ folder in the main clone by default. To publish the markdown files from this repo’s wiki/ directory:

1. Enable the wiki

On GitHub: Repository → Settings → Features → Wiki → enable.

2. Clone the wiki repo (empty the first time)

git clone https://github.com/OpenGraph-AI/OpenAgent.wiki.git
cd OpenAgent.wiki

If the wiki is empty, you may get an empty repo or a default Home.md — that is fine.

3. Copy files from the main repo

From your machine (adjust paths):

cp /path/to/OpenAgent/wiki/*.md .

Or symlink/copy only the pages you want.

4. Commit and push

git add .
git status
git commit -m "Import wiki pages from main repo wiki/ folder"
git push origin master

GitHub wiki default branch is often master for the wiki remote; if main is used, run git branch after clone and push accordingly.

5. Optional: _Sidebar.md

If you added _Sidebar.md, it appears as a custom sidebar on the wiki. Internal links use wiki syntax, e.g. [Quickstart](Quickstart).

Keeping wiki in sync

Options:

  • Manual: Repeat copy + commit when docs change.
  • Automation: A small CI job or script that clones OpenAgent.wiki.git, copies wiki/*, commits, and pushes (use a scoped PAT or deploy key with wiki push access; store secrets in GitHub Actions secrets).

Do not commit long-lived tokens into the main repo.

Quickstart

Prerequisites

  • Python 3.10+
  • An OpenAI-compatible API key (OpenAI, Azure OpenAI with compatible base URL, Groq, etc.)

Run locally

git clone https://github.com/OpenGraph-AI/OpenAgent.git
cd OpenAgent
pip install -r requirements.txt
cp .env.example .env

Edit .env and set at least:

LLM_API_KEY=sk-...   # required

Optional but common:

LLM_BASE_URL=https://api.openai.com/v1   # default if omitted
LLM_MODEL=gpt-4o                         # default if omitted

Start the server:

python run.py

By default the app listens on 0.0.0.0:8000 (see HOST / PORT in .env).

Open the UI

With the default layout, the server mounts the frontend under /static and may serve / as the main app when the frontend/ directory is present.

Try:

If you only have the public/ tree in your deployment, follow your host’s static file rules or the README for that layout.

Docker

From the repo root:

docker compose up

Use the same .env (or compose overrides) for LLM_API_KEY and optional keys.

Next steps

Clone this wiki locally