Agent servers

An agent server is the Python process that runs agents inside your organization. The process is a FastAPI application served by Uvicorn, fully asynchronous, with exactly one worker. Run one server on a laptop or several behind a load balancer; any server can serve any request. Below: the command line, the addresses a server serves, how servers are configured, and what they report.

The command line

Options on the search2o command line are passed through to Uvicorn, so the Uvicorn options for the address, the port and TLS all work as documented by Uvicorn. A few options are refused because the agent server runs as exactly one worker per process:

--reload  --reload-dir  --reload-include  --reload-exclude  --reload-delay
--factory
--workers

To use more than one worker's worth of capacity, run more servers rather than more workers.

What a server serves

By default a server listens on 127.0.0.1:9020 and serves:

Address	What is there
`http://127.0.0.1:9020/ui`	The GUI
`http://127.0.0.1:9020/openapi.json`	The OpenAPI schema
`http://127.0.0.1:9020/docs`	Swagger UI
`http://127.0.0.1:9020/redoc`	ReDoc

All of these paths are settings in the server's configuration, described next.

Named server configurations

The Agent servers page holds one or more named configurations. The configuration named default is required, and a server uses it unless told otherwise. To run a server under another configuration, append the name to the license key value: SEARCH2O_LICENSE_KEY=your-license-key/edge starts the server with the configuration named edge. Use separate configurations when servers differ in what they serve, for example a server that serves the GUI and a server that answers only REST calls.

What a configuration sets

Field	Type	Default	Description
`uiPath`	string	"/ui"	The path the bundled UI is served at. Leave it empty to not serve the UI at all.
`routes`	list of "owner" \| "admin" \| "dev" \| "user" \| "auth" \| "exec" \| "reports"		The list of routes to serve.
`connectPageUrl`	string		The page where a user approves an integration's request for access. Leave it empty and it follows the UI path above, which is what keeps the two in step. Set a page under that path for a UI of your own, such as connect, or a full address for a UI hosted elsewhere, such as https://ui.example.com/connect. Whatever is set must point at where the UI is really served. The request is added to it as a query parameter named c.
`allowCrossOrigin`	list of string	['*']	Other origins allowed to call this API, such as https://ui.example.com.
`docsUrl`	string	"/docs"	Where the API documentation is served.
`redocUrl`	string	"/redoc"	Where the ReDoc documentation is served.
`openapiUrl`	string	"/openapi.json"	Where the OpenAPI schema is served.
`logs`	object of string → JSON value		Logging configuration for the agent server.
`cloudPool`	ConnectionPoolModel		How this agent server connects to the Search2o cloud. It carries connection settings only: it is deliberately not one of the API connection pools, and it has no certificate fields, so nothing configured for an agent can change how this server reaches the Search2o cloud. A server behind a proxy that re-signs TLS trusts that proxy through the SSL_CERT_FILE environment variable, which is where a machine-wide trust setting belongs. Changing any of this needs an agent server restart.

These settings are read once, at startup, so a change takes effect when the server restarts. The logs object is a standard Python logging configuration dictionary. The UI path may point anywhere the server can read; leave the UI path empty to serve no GUI. The documentation paths can be moved or set to nothing to switch the interactive API documentation off.

Startup errors

Problems found at startup — an allowlist entry the server cannot import, or an LLM adapter that fails to instantiate — are written to the server's log. Errors are logged locally on the server and do not appear in the GUI.

Running many servers

The server is stateless, so you are free to containerize it and run it load balanced; nothing more is needed, and there is no explicit limit today on the number of servers you run. Every server picks up a configuration or profile change before its next agent run, so servers never drift from each other; see The agent runtime. The exceptions are the settings on this page, which need a restart, and the license key, which every server must be restarted with after a rotation.

Health

GET /health is answered by the server itself, without sign-in, and is the call for a load balancer or a monitor to use. It reaches nothing outside the agent server, so its response time reflects that server's own health. See Agent server sizing.