Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuaiZai233/FrostAgent/llms.txt

Use this file to discover all available pages before exploring further.

FrostAgent exposes all of its HTTP surface on a single port configured by LISTEN_ADDR (default :8080). The embedded management SPA is served at / and ConnectRPC services are mounted at /frostagent.v1.*. A separate WebSocket server for the OneBot adapter listens on WS_LISTEN_ADDR (default 0.0.0.0:1234).
GET /health and POST /agent/query are referenced in the project README but are not registered as handlers in cmd/app/main.go in the current codebase. Requests to those paths fall through to the SPA catch-all handler and return index.html, not the JSON responses described below. The sections below document the intended interface as described in the README; treat them as forthcoming endpoints until dedicated handlers are added to main.go.

​
Base URL

http://localhost:8080
Change the port by setting LISTEN_ADDR in your .env file, for example LISTEN_ADDR=:9090.

​
GET /health

A lightweight liveness check intended to return a fixed JSON body with no dependencies on the engine state — useful for load balancer or container health checks.
This endpoint is documented in the README but has no registered handler in cmd/app/main.go. Requests to /health currently reach the SPA fallback and return index.html. Add a dedicated handler before relying on this endpoint in production.
Request No request body or query parameters. Response 
{ "status": "ok" }
Example 
curl http://localhost:8080/health

​
POST /agent/query

The intended stateless agent endpoint. Accepts a user message or a full message history, runs it through the FrostAgent engine (including all registered tools), and returns the agent’s reply as a plain string. No session state is created or persisted between calls.
This endpoint is documented in the README but has no registered handler in cmd/app/main.go. Requests to /agent/query currently reach the SPA fallback and return index.html. Add a dedicated handler that calls Engine.RunMessages before relying on this endpoint.
Request body
​
input
string
A plain-text user message. Optional when messages is provided. If both input and messages are present, input is appended as the final user message after the provided history.
​
messages
array
An explicit message history. Each element must have a role ("user" or "assistant") and a content string. Optional when input is provided.
Response The raw string returned by Engine.RunMessages — the agent’s final answer after all tool iterations have completed. The response is returned as a plain JSON string value. Example 1 — simple input 
curl -X POST http://localhost:8080/agent/query \
  -H "Content-Type: application/json" \
  -d '{ "input": "Tell me about the weather in Beijing." }'
Example 2 — message history only 
curl -X POST http://localhost:8080/agent/query \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user",      "content": "My name is Frost." },
      { "role": "assistant", "content": "Nice to meet you, Frost." },
      { "role": "user",      "content": "What is my name?" }
    ]
  }'
Example 3 — history with a new input appended 
curl -X POST http://localhost:8080/agent/query \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user",      "content": "My name is Frost." },
      { "role": "assistant", "content": "Nice to meet you, Frost." }
    ],
    "input": "What did I just tell you my name was?"
  }'
/agent/query is fully stateless — each request is an isolated run with no session persistence. If you need conversation memory across multiple turns from the same user, use the OneBot adapter (/adapters/onebot), which calls Engine.RunWithSession and maintains per-session history automatically.

​
Management SPA (GET /)

The embedded single-page application is served from internal/frontend/dist/index.html and is mounted as the catch-all route at /. It provides a browser-based interface for:
  • Bot Status — real-time overview and active session list (backed by BotStatusService)
  • Settings — environment variable editor with secret masking (backed by SettingsService)
  • Log Viewer — filterable, paginated log browser with live streaming (backed by LogService)
Navigate to http://localhost:8080 in your browser after starting FrostAgent to access the management panel.

​
WebSocket endpoint (ws://host:1234/ws/frostagent)

The OneBot adapter WebSocket endpoint listens on a separate port from the HTTP server. It is not an HTTP REST endpoint and is documented fully in the OneBot adapter reference (/adapters/onebot). Key details:
  • Default address: ws://0.0.0.0:1234/ws/frostagent
  • Configurable via WS_LISTEN_ADDR in .env
  • Implements the OneBot v11 reverse WebSocket protocol
  • Routes group and private messages to stateful Engine.RunWithSession calls

​
CORS

All HTTP responses from the main server include permissive CORS headers set by the corsMiddleware wrapper in main.go:
HeaderValue
Access-Control-Allow-Origin*
Access-Control-Allow-Credentialstrue
Access-Control-Allow-MethodsPOST, OPTIONS, GET, PUT, DELETE
Access-Control-Allow-HeadersContent-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With
OPTIONS preflight requests receive a 204 No Content response immediately without being forwarded to any handler.
The default CORS policy allows requests from any origin (*). For production deployments, consider placing FrostAgent behind a reverse proxy that enforces stricter origin policies.

Build docs developers (and LLMs) love

Get started for freeTalk to us