Skip to content

Built-in Agent

Run the fixed-flow local chat service.

The built-in Agent is a FastAPI service that provides fixed-flow RAG chat over Cortrix storage. It queries cortrix-server through the public Python SDK and has no privileged channel:

Web UI chat -> Cortrix Agent (:8001) -> Python SDK -> cortrix-server (:8420)
                                    -> configured LLM provider
Note

The setup steps and interface details on this page come from cortrix-agent/README.md in the repository. The built-in Agent needs a working LLM service, and it hasn’t been tested for this page. The quickstart leaves the built-in Agent off by default.

Current scope

The built-in Agent has one mode: chat, a fixed RAG flow with no autonomous tool selection. It’s in preview.

Persisting configuration through PUT /config/agent_llm hasn’t been verified for this documentation.

Prerequisites

  • A running Cortrix service.
  • Python 3.
  • Credentials for an LLM service, for the agent_llm role.

Start the service

cd cortrix-agent
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
.venv/bin/uvicorn main:app --port 8001 --reload

Put your LLM service configuration in .env. Keep real keys only in ignored local files such as .env, and don’t commit them.

Health check

curl http://localhost:8001/health

The expected response shape:

{
  "status": "ready",
  "cortrix_server": "unknown",
  "llm_reachable": true
}

In v1.0.0-rc.2, cortrix_server is always "unknown": this endpoint doesn’t check the Cortrix server. Use the server’s own readiness endpoint for that. If llm_reachable is false, check the LLM service configuration.

Chat interface

POST /chat streams the answer over server-sent events:

curl -N -X POST 'http://localhost:8001/chat?explain=true' \
  -H 'Content-Type: application/json' \
  -H 'X-Cortrix-Namespace: default' \
  -d '{"message": "find privacy documents", "session_id": "s-001"}'
InputLocationNotes
messageRequest bodyThe user message
session_idRequest bodyAn optional session identifier
AuthorizationHeaderAn optional Bearer token, depending on the server’s authentication mode
X-Cortrix-Tenant-IdHeaderAn optional tenant identifier
X-Cortrix-NamespaceHeaderOptional. Names the namespace
explain=trueQuery parameterReturns extra explanation metadata
debug=trueQuery parameterReturns more detail on failure

Example SSE frames:

data: {"chunk": "Based on"}
data: {"chunk": " the retrieved documents..."}
data: {"meta": {"session_id": "s-001", "chunk_ids": [], "rag_status": "success"}}
data: [DONE]

Errors come back as structured SSE error events with a code, a message, retryability, a category, an optional retry delay, and structured data.

Other endpoints

EndpointPurpose
GET /sessions/{id}Returns the recent turns a session keeps in memory
GET /configReturns the current LLM configuration with the API key masked
GET /config/providersReturns the LLM provider catalog used by the configuration UI
PUT /config/agent_llmUpdates the LLM configuration. Persisting it isn’t a verified capability yet
GET /healthReturns service status, backend reachability, and LLM reachability

Next steps