Creating your own client

The agent server publishes an OpenAPI schema, so a client in any language can be generated with standard tools.

Generating a client

$ curl http://127.0.0.1:9020/openapi.json > openapi.json
$ npx orval --input openapi.json --output ./search2o-client   # TypeScript
$ openapi-generator-cli generate -i openapi.json -g python     # Python, Java, Go, ...

The schema carries every request and response model, including the streamed line types of execAgent, so a generated client knows the shapes without hand-written definitions.

A client in a browser

A browser client that is not served by the agent server runs on a different origin. Add that origin to the allowed CORS origins in the Agent servers configuration, or the browser will refuse the calls. We would suggest the session cookie rather than a bearer token: the cookie is HTTP-only and never visible to page scripts.

Rules a client must follow

• It is best to send only the fields an endpoint declares. An unknown field is rejected with status 422.
• Check success in every response, and show errorMessage to the user when it is false; the message is written for that purpose.
• Sign in again when a response carries mustLogin: true, then repeat the call.
• The convid from an execAgent response is worth keeping if the user may follow up.
• A streamed response is read line by line, rather than waiting for the whole body.