English · 简体中文

CornAgent — Open-source Full-stack AI Agent

Bring an AI agent into your application.
An embeddable React interface and FastAPI agent runtime. Self-host with streaming, pause and resume, durable state, and parallel multi-agent subtasks.

Quick Start · Users · Integration · Tools · Recovery · Documentation

View the Demo

Why CornAgent?

CornAgent is an open-source, full-stack AI agent. Use it as a self-hosted AI agent application, or embed its React agent sidebar into an existing product. The FastAPI agent runtime manages tool calls, parallel multi-agent subtasks, and persistent execution state.

Building an agent product also requires sessions, streaming events, pausing, recovery, and user interactions. CornAgent brings these capabilities together in one independently installable project, with a shared runtime for the chat page and sidebar.

Quick Start

Install Python 3.12, uv, Node.js 22+, PostgreSQL, and Redis. You can use existing local PostgreSQL and Redis instances.

git clone https://github.com/XiaoTongYuCode/CornAgent.git
cd CornAgent
cp -n .env.example .env

Edit .env in the project root to set your model API key and verify the PostgreSQL and Redis connection settings. Then run:

make setup
make dev

Open http://127.0.0.1:5173/chat.

make setup installs the locked frontend and backend dependencies, creates the cornagent database, and applies migrations. By default, PostgreSQL uses the current system user on local port 5432; Redis uses local port 6379.

Models and Configuration

All configuration options are listed in .env.example at the project root. Use .env for local overrides; system environment variables take precedence. Restart the service after changing configuration.

• Models: Connected through LiteLLM. The default configuration uses DeepSeek; OpenAI-compatible chat and tool-calling APIs are also supported. Image input requires a vision-capable model.
• Persistence: PostgreSQL stores sessions, messages, and run state; Redis Streams deliver live events.
• Attachments: Local filesystem and S3-compatible object storage are supported.
• Runtime settings: Listening addresses, ports, concurrency, timeouts, context budgets, and attachment limits are configurable.

Model API keys are used only on the server, and .env is excluded from version control. Without a model API key, the service can still start and load history; the interface indicates that the agent is unavailable.

User System

The user system is disabled by default, so the local quick start still uses a shared workspace. Enable it to choose between two authentication modes:

When enabled, sessions, messages, attachments, runs, and SSE are isolated by user. Identity and email delivery adapters are replaceable; the login UI lives in the application layer, and shared Agent components do not depend on the account system. Invisible mode does not collect hardware fingerprints or prove a person's identity. Organizations, administrators, and roles are not included.

For local invisible mode, set these values in the root .env:

CORNAGENT_USERS_ENABLED=true
CORNAGENT_AUTH_MODE=invisible
CORNAGENT_AUTH_ORIGIN=http://127.0.0.1:5173
CORNAGENT_AUTH_COOKIE_SECURE=false

Generate a persistent random secret with python3 -c 'import secrets; print(secrets.token_urlsafe(48))' and save it as CORNAGENT_AUTH_SECRET in .env. In production, use the actual HTTPS origin and keep CORNAGENT_AUTH_COOKIE_SECURE=true. Apply migrations using the upgrade steps below and restart. See the user system guide for full configuration, identity switching, and extension interfaces (Simplified Chinese).

The live site has invisible login enabled; its deployment record is in ECS deployment. This does not change the project defaults. Existing shared history is not assigned to the first visitor, and switching authentication modes does not merge history.

Embed in Your Application

Within this project, use three components to add an agent to a page:

import { AgentLauncher, AgentSidebar, CornAgentProvider } from './agent'
import './styles.css'

export default function App() {
  return (
    <CornAgentProvider>
      <main>
        <h1>My Application</h1>
        <AgentLauncher />
      </main>
      <AgentSidebar />
    </CornAgentProvider>
  )
}

The chat page, launcher, and panel share sessions under the same provider. For custom API paths, request adapters, and page layouts, see the frontend integration guide (Simplified Chinese). Components are provided as source code; there is currently no standalone npm package.

Usage analytics is available at /usage, with optional tool/model event collection. See usage analytics for metric definitions and the pluggable collector.

Tools and Subtasks

Built-in tools include ask_user, read_file, web_search, read_url, and five subtask orchestration tools. The main agent can continue working, then wait for and collect subtask results as needed. Subtasks have their own durable state and cancellation mechanism.

web_search uses Tavily Search; read_url uses Tavily Extract. Both require tavily_api_key in .env. Both are available to the main agent and subagents. See web tools.

The optional mock_web_search is disabled by default and returns fixed, fictional material for demonstrating search and task orchestration. Both the interface and model prompts identify it as simulated. Reasoning by the main agent and subagents still uses your configured model API.

For tool registration, parameter contracts, subtask lifecycles, and demo prompts, see subtasks and tool extensions (Simplified Chinese).

Architecture

React Chat Page / Agent Sidebar
            │ JSON · File Uploads · SSE
            ▼
       FastAPI / Agent Runtime
            ├── LiteLLM → Models and tool calls
            ├── PostgreSQL → Sessions, message trees, checkpoints, and task state
            ├── Redis Streams → Live events and bounded replay
            └── Local Filesystem / S3 → Private attachments

PostgreSQL is the source of truth for durable state; Redis handles live event delivery. Recovery after page refreshes and service restarts is described below.

For detailed boundaries, see architecture, runtime, and file storage (Simplified Chinese).

Recovery and Data Persistence

Sessions, message branches, run checkpoints, pending questions, and subtask state are stored in PostgreSQL. After an application process crashes and restarts, a background reconciler checks expired leases and takes over recoverable runs from safe checkpoints. Leases and monotonically increasing fencing tokens prevent stale executors from continuing to write run state.

Retaining session data and automatically continuing the current run are separate guarantees. Before retrying an interrupted ordinary tool, verify the outcome of its external operation. A failed run does not mean the external operation never happened.

Recovery requires intact PostgreSQL and attachment storage, with the restarted service connecting to the same persisted data. Continued execution also requires dependencies such as Redis and the model API to become available again. Use persistent storage for the database and attachments; multiple instances must share an attachment volume or S3-compatible bucket. Backups must cover both the database and attachments. Do not rely on an ephemeral container filesystem.

These mechanisms cover application process failures. Disasters such as database or disk corruption and host loss require deployment-specific backups, highly available storage, and recovery drills. The project does not guarantee zero data loss or a fixed recovery time under arbitrary failures.

See agent runtime for checkpoint, lease, and tool failure semantics; file storage for persistence requirements; and testing and verification for documented recovery test coverage (Simplified Chinese).

Development and Builds

make check   # Backend lint and tests; frontend lint and tests
make build   # TypeScript checks and frontend production build

After building, FastAPI can serve the frontend from the same origin:

cd server
CORNAGENT_SERVER_RELOAD=false uv run python -m app.serve

When upgrading an existing installation, stop the service before applying database migrations:

cd server
uv run alembic upgrade head

Regression tests against real PostgreSQL and Redis create and clean up their own random schema without clearing existing databases or Redis data:

cd server
CORNAGENT_TEST_POSTGRES_URL=postgresql+psycopg://localhost:5432/cornagent \
CORNAGENT_TEST_REDIS_URL=redis://127.0.0.1:6379/0 uv run pytest -q

By default, the project listens locally with the user system disabled, and all browsers share one workspace. For external deployments, enable the user system above or integrate a host identity adapter. See ECS deployment; Vercel deployment remains an optional alternative.

Documentation

The detailed guides below are currently available in Simplified Chinese.

Contributing

Use issues to report bugs or discuss features, and pull requests to contribute improvements. Run make check and make build before submitting. Changes to the state machine, SSE, storage, or message branches should also verify refresh and recovery behavior. Do not commit secrets, user conversations, uploaded files, or runtime data.

When updating this README, keep the Simplified Chinese version in sync, including examples, links, and behavior descriptions.

License

CornAgent is released under the MIT License. See NOTICE for attribution to source projects and third-party dependencies.