Hayride AI

Hayride AI API

The Hayride AI Server provides a dedicated API for AI-based interactions. This server is enabled by activating the ai feature prior to initialization:

hayride config features enable ai
hayride init

or by activating the ai feature and using the enabled ai feature command:

hayride config features enable ai
hayride ai init

Once initialized, the server exposes HTTP endpoints that allow interaction with AI agents using structured message payloads.

warning

The Hayride AI API is currently in alpha. Breaking changes may occur in upcoming releases. Please consult release notes and this documentation when integrating with this API.

Configuration

To use the AI server, your Hayride configuration file must define the ai feature with both a binary and HTTP address and the components used to compose a full ai server.

Hayride installs with default values, which can be customized as needed:

features:
    ai:
        enabled: true
        bin: "hayride-core:ai-server@0.0.1"
        compose:
            context: "hayride:inmemory@0.0.1"
            tools: "hayride:default-tools@0.0.1"
            model: "hayride:llama31@0.0.1"
            agents: "hayride:default-agent@0.0.1"
            store: "hayride-core:cfg@0.0.1"
        http:
            port: 8082

tip

For detailed configuration options, see the Configuration Guide .

API Endpoints

Post /v1/generate

Submits a generation request to the AI agent. This endpoint accepts a payload containing the desired model, a system message, and a list of structured messages and returns one or more generated responses. Depending on the agent, the result may be a single message or a sequence from an agent loop.

Request

Content-Type: application/json

Body:

{
  "data": {
    "generate": {
    "model": "bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/Meta-Llama-3.1-8B-Instruct-IQ2_M.gguf",
    "system": "You are a helpful assistant",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "text": {
              "text": "Hello, how are you?",
              "content-type": "text/plain"
            }
          }
        ]
      }
    ]
    }
  }
}

Response

Returns a list of messages generated by the AI agent.

{
  "data": {
    "messages": [
      {
        "role": "assistant",
        "content": [
          {
            "text": {
              "text": "Im just a helpful assistant, Im functioning properly. How can I assist you today?",
              "content-type": "text"
            }
          }
        ]
      }
    ]
  }
}