The ChatAgents backend is a FastAPI application that powers intelligent conversational agents built on LangGraph’s ReAct architecture and Tavily’s web-search tooling. It listens on portDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/EllisYuan/ChatAgents/llms.txt
Use this file to discover all available pages before exploring further.
8080 and exposes two distinct surface areas: a streaming inference endpoint (/stream_agent) for real-time agent responses, and a full CRUD REST API (/api/sessions/*) for managing conversation history. FastAPI automatically generates interactive API documentation, so you can explore and test every endpoint without writing any client code.
Base URL
| Environment | Base URL |
|---|---|
| Local development | http://localhost:8080 |
| Docker (frontend → backend) | http://backend:8080 |
| Production (via Nginx) | https://your-domain.com/api |
Authentication
The streaming endpoint reads API keys from request headers at inference time. If a header is absent, the server falls back to the corresponding environment variable.| Header | Environment Variable | Required For |
|---|---|---|
X-Tavily-Key | TAVILY_API_KEY | All /stream_agent requests |
X-Claude-Key | ANTHROPIC_API_KEY | Claude provider |
X-OpenAI-Key | OPENAI_API_KEY | OpenAI provider |
X-Groq-Key | GROQ_API_KEY | Groq provider |
The session management API (
/api/sessions/*) does not require any authentication headers. All CRUD operations on conversation history are open by default.Endpoint Summary
| Method | Path | Description |
|---|---|---|
GET | / | Health check — returns server status |
GET | /health | Health check used by the frontend container |
POST | /stream_agent | Run the ReAct agent and stream NDJSON events |
GET | /api/sessions | List all sessions (metadata only) |
GET | /api/sessions/{session_id} | Retrieve a single session with full message history |
POST | /api/sessions | Create a new empty session |
PUT | /api/sessions/{session_id} | Rename an existing session |
DELETE | /api/sessions/{session_id} | Permanently delete a session |
NDJSON Streaming Format
The/stream_agent endpoint returns Content-Type: application/json but delivers its body as newline-delimited JSON (NDJSON) — one complete JSON object per line. Clients should read the response body line-by-line and parse each line independently as it arrives.
There are four event types that can appear in the stream:
LLM token — a text chunk from the language model:
operation_index field is a monotonically increasing counter scoped to the current request — it lets you correlate each tool_start with its corresponding tool_end even if multiple tools run in the same session.
Auto-Generated API Docs
FastAPI automatically generates two interactive documentation UIs from the application’s route definitions and Pydantic models:- Swagger UI —
http://localhost:8080/docs— lets you try every endpoint directly in the browser - ReDoc —
http://localhost:8080/redoc— provides a clean, read-only reference layout
Explore the API
POST /stream_agent
Stream real-time agent responses and tool call events over NDJSON. Supports Fast and Deep Thinking modes across Claude, OpenAI, and Groq.
Sessions API
CRUD endpoints for managing conversation sessions stored as JSON files on disk. List, create, retrieve, rename, and delete sessions.