Built-in Agent
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:
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_llmrole.
Start the service
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
The expected response shape:
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:
| Input | Location | Notes |
|---|---|---|
message | Request body | The user message |
session_id | Request body | An optional session identifier |
Authorization | Header | An optional Bearer token, depending on the server’s authentication mode |
X-Cortrix-Tenant-Id | Header | An optional tenant identifier |
X-Cortrix-Namespace | Header | Optional. Names the namespace |
explain=true | Query parameter | Returns extra explanation metadata |
debug=true | Query parameter | Returns more detail on failure |
Example SSE frames:
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
| Endpoint | Purpose |
|---|---|
GET /sessions/{id} | Returns the recent turns a session keeps in memory |
GET /config | Returns the current LLM configuration with the API key masked |
GET /config/providers | Returns the LLM provider catalog used by the configuration UI |
PUT /config/agent_llm | Updates the LLM configuration. Persisting it isn’t a verified capability yet |
GET /health | Returns service status, backend reachability, and LLM reachability |
Next steps
- Choose an access path
- Configuration: configure LLMs by role.
- Compatibility and status