> For the complete documentation index, see [llms.txt](https://docs.rierino.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rierino.com/data-science/genai-models/ai-agent-apis.md).

# AI Agent APIs

All runners which include GenAI base runner and have GenAI models assigned to them can service the following common APIs for describing and interacting with agents.

## Gets detailed view of AI agent capabilities

> Returns sagas, states, systems and scripting languages an agent can utilize.

```json
{"openapi":"3.0.0","info":{"title":"Rierino - Core Platform - AI Agent APIs","version":"1.0.0"},"servers":[{"url":"https://gateway_server","description":"API gateway server"}],"paths":{"/api/request/{channel}/GetAIAgent":{"get":{"summary":"Gets detailed view of AI agent capabilities","description":"Returns sagas, states, systems and scripting languages an agent can utilize.","tags":["ai"],"parameters":[{"$ref":"#/components/parameters/channelParam"},{"name":"id","in":"query","description":"Id of agent to view","required":false,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GenericOK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Id of the agent"},"data":{"type":"object","properties":{"name":{"type":"string","description":"Name of the agent"},"description":{"type":"string","description":"Description of the agent"},"states":{"type":"array","description":"List of state managers accessible by agent"},"systems":{"type":"array","description":"List of external systems accessible by agent"},"sagas":{"type":"array","description":"List of sagas that can be executed by agent"},"prompts":{"type":"array","description":"List of predefined prompts"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"},"501":{"$ref":"#/components/responses/NotImplemented"}}}}},"components":{"parameters":{},"responses":{"GenericOK":{"description":"OK"},"Unauthorized":{"description":"Authorization information is missing or invalid."},"Forbidden":{"description":"User does not have the required role for access."},"InternalError":{"description":"Server failed to process request due to internal errors."},"NotImplemented":{"description":"Feature is not implemented by the server."}}}}
```

## Calls an AI agent

> Makes a request to a specific AI agent with a message or prompt inputs.

```json
{"openapi":"3.0.0","info":{"title":"Rierino - Core Platform - AI Agent APIs","version":"1.0.0"},"servers":[{"url":"https://gateway_server","description":"API gateway server"}],"paths":{"/api/request/{channel}/CallAIAgent":{"post":{"summary":"Calls an AI agent","description":"Makes a request to a specific AI agent with a message or prompt inputs.","tags":["ai"],"requestBody":{"description":"AI agent request details","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"string","description":"Id of the agent to call","required":true},"chat":{"type":"string","description":"Id of the ongoing chat with agent"},"message":{"type":"string","description":"Message/request to send to agent, required if prompt is not used"},"prompt":{"type":"string","description":"Id of the agent prompt to be used, required if message is not used"},"input":{"type":"object","description":"Input parameters which are used by the selected prompt"},"request":{"type":"object","description":"Optional LLM parameters that can be customized per request","properties":{"responseFormat":{"type":"object","description":"Format of the response to be produced by agent","properties":{"type":{"type":"string","description":"Expected response format type","enum":["TEXT","JSON","JSON_SCHEMA"]},"jsonSchema":{"type":"string","description":"Json schema for the response data model"},"schemaName":{"type":"string","description":"Name of the schema to use"},"strict":{"type":"boolean","description":"Whether format requirement is strict"}}},"model":{"type":"string","description":"ID or name of the model to use for the request."},"temperature":{"type":"number","description":"Controls randomness in the output. Lower values make responses more focused and deterministic; higher values make them more creative and varied."},"topP":{"type":"number","description":"Controls nucleus sampling by limiting token selection to the most probable tokens whose cumulative probability is at least this value. Lower values make output more focused."},"maxTokens":{"type":"number","description":"Maximum number of tokens to generate in the response."},"maxCompletionTokens":{"type":"number","description":"Maximum number of tokens allowed for the model's completion, including visible output and any internal reasoning tokens supported by the model."},"frequencyPenalty":{"type":"number","description":"Penalizes tokens based on how often they have already appeared, reducing repetition in the output."},"presencePenalty":{"type":"number","description":"Penalizes tokens that have already appeared at least once, encouraging the model to introduce new topics or wording."},"stopSequences":{"type":"array","description":"One or more strings where the model should stop generating further output."},"seed":{"type":"number","description":"Seed value used to make responses more reproducible when supported by the model and other parameters remain the same."}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/GenericOK","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"string","description":"Response text generated by the agent"},"chat":{"type":"string","description":"Id of the chat created/ongoing"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"},"501":{"$ref":"#/components/responses/NotImplemented"}}}}},"components":{"responses":{"GenericOK":{"description":"OK"},"Unauthorized":{"description":"Authorization information is missing or invalid."},"Forbidden":{"description":"User does not have the required role for access."},"InternalError":{"description":"Server failed to process request due to internal errors."},"NotImplemented":{"description":"Feature is not implemented by the server."}}}}
```

## Calls a 'panel' of AI agents

> Makes the same request to a list of AI agents and collects responses from all.

```json
{"openapi":"3.0.0","info":{"title":"Rierino - Core Platform - AI Agent APIs","version":"1.0.0"},"servers":[{"url":"https://gateway_server","description":"API gateway server"}],"paths":{"/api/request/{channel}/CallAIPanel":{"post":{"summary":"Calls a 'panel' of AI agents","description":"Makes the same request to a list of AI agents and collects responses from all.","tags":["ai"],"requestBody":{"description":"AI panel request details","content":{"application/json":{"schema":{"type":"object","properties":{"panel":{"type":"array","description":"List of AI agents to call","items":{"type":"object","properties":{"agent":{"type":"string","description":"Id of the agent to call"},"weight":{"type":"number","description":"Weight to assign to agent response"},"chat":{"type":"string","description":"Id of the ongoing chat with agent"}}}},"message":{"type":"string","description":"Message/request to send to agent, required if prompt is not used"},"prompt":{"type":"string","description":"Id of the agent prompt to be used, required if message is not used"},"input":{"type":"object","description":"Input parameters which are used by the selected prompt"}}}}}},"responses":{"200":{"$ref":"#/components/responses/GenericOK","content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"array","items":{"properties":{"agent":{"type":"string","description":"Agent that generated the response"},"weight":{"type":"number","description":"Weight assigned to responding agent"},"response":{"type":"string","description":"Response text generated by the agent"},"chat":{"type":"string","description":"Id of the chat created/ongoing"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"},"501":{"$ref":"#/components/responses/NotImplemented"}}}}},"components":{"responses":{"GenericOK":{"description":"OK"},"Unauthorized":{"description":"Authorization information is missing or invalid."},"Forbidden":{"description":"User does not have the required role for access."},"InternalError":{"description":"Server failed to process request due to internal errors."},"NotImplemented":{"description":"Feature is not implemented by the server."}}}}
```

## Summarizes an AI chat

> Makes a request to a specific AI agent to summarize current messages in a given chat.

```json
{"openapi":"3.0.0","info":{"title":"Rierino - Core Platform - AI Agent APIs","version":"1.0.0"},"servers":[{"url":"https://gateway_server","description":"API gateway server"}],"paths":{"/api/request/{channel}/SummarizeAIChat":{"post":{"summary":"Summarizes an AI chat","description":"Makes a request to a specific AI agent to summarize current messages in a given chat.","tags":["ai"],"requestBody":{"description":"Summary request details","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"string","description":"Id of the agent to call","required":true},"chat":{"type":"string","description":"Id of the ongoing chat with agent"}}}}}},"responses":{"200":{"$ref":"#/components/responses/GenericOK","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"string","description":"Response summary generated by the agent"},"chat":{"type":"string","description":"Id of the chat created/ongoing"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"},"501":{"$ref":"#/components/responses/NotImplemented"}}}}},"components":{"responses":{"GenericOK":{"description":"OK"},"Unauthorized":{"description":"Authorization information is missing or invalid."},"Forbidden":{"description":"User does not have the required role for access."},"InternalError":{"description":"Server failed to process request due to internal errors."},"NotImplemented":{"description":"Feature is not implemented by the server."}}}}
```

## Rates a message from AI agent

> Submits a positive or negative feedback for an AI response.

```json
{"openapi":"3.0.0","info":{"title":"Rierino - Core Platform - AI Agent APIs","version":"1.0.0"},"servers":[{"url":"https://gateway_server","description":"API gateway server"}],"paths":{"/api/request/{channel}/RateAIMessage":{"post":{"summary":"Rates a message from AI agent","description":"Submits a positive or negative feedback for an AI response.","tags":["ai"],"requestBody":{"description":"Rating details","content":{"application/json":{"schema":{"type":"object","properties":{"chat":{"type":"string","description":"Id of the rated chat"},"responseId":{"type":"string","description":"Id of the agent message to rate"},"rating":{"type":"number","description":"User rating (typically -1 for negative, 1 for positive)"}}}}}},"responses":{"200":{"$ref":"#/components/responses/GenericOK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"},"501":{"$ref":"#/components/responses/NotImplemented"}}}}},"components":{"responses":{"GenericOK":{"description":"OK"},"Unauthorized":{"description":"Authorization information is missing or invalid."},"Forbidden":{"description":"User does not have the required role for access."},"InternalError":{"description":"Server failed to process request due to internal errors."},"NotImplemented":{"description":"Feature is not implemented by the server."}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rierino.com/data-science/genai-models/ai-agent-apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.