Search2oSearch2o
Docs / REST API

Automating tasks with an LLM

The OpenAPI schema at /openapi.json describes every endpoint of the agent server precisely enough for an LLM to call the API. Hand the schema to a model or to a coding assistant, and administrative and reporting tasks can be automated in plain language.

What the schema gives a model

The schema names every endpoint, the fields of each request with their types and constraints, and the shape of each response. That is the same information a tool-calling model needs: most agent frameworks and coding assistants accept an OpenAPI document directly and turn each endpoint into a tool the model can call. The model then reads the descriptions, picks the endpoint, and fills in the body.

$ curl http://127.0.0.1:9020/openapi.json > search2o-openapi.json

Giving the model access

  1. Create a service account for the automation, with the lowest role that covers the task. A user role covers search and conversations, a developer covers agents and agent reports, and an administrator covers users and usage reports.
  2. Give the model's tool layer the service account's key, so that every call carries Authorization: Bearer …. See Authentication.
  3. It helps to tell the model the base URL of the agent server, and that every endpoint is a POST with a JSON body.

Tasks that suit this

  • Reporting. "Which agents failed most last week, and with what error?" The model calls getAgentErrorReport for the window and reads the result; a follow-up calls getAgentErrorDetailReport for one agent.
  • User administration. "Add these twelve people as developers." The model calls addUsers with the list, up to 25 at a time.
  • Agent housekeeping. "Retag every agent that mentions finance in its title as corporate." The model lists agents with getAgentList, then calls updateTag for each match.
  • Running agents. "Run the morning briefing for the payments team and send me the answer." The model calls execAgent without stream and returns the output; see Running agents.

Keeping it safe

A model with the schema can call anything the signed-in user may call, including deleteAgent, deleteUsers and updateRole. The role of the automation user is the boundary. The role is best kept as low as the task allows, and a user-role account suffices where a report is all that is needed. Every call the model makes is an ordinary API call. Search2o Cloud checks the call against the role, records the call against the automation user, and shows the call in the reports and notifications like any other.

For people rather than models

The same schema is rendered for people. Swagger UI at /docs lets you fill in a request and send it from the browser. ReDoc at /redoc is a reference to read. Both are served by the agent server and can be moved or switched off in the Agent servers configuration.