First, navigate to the Admin console, and go to the Tools tab. Click the New Tool button.

Next, specify a OpenAPI 3.0 or OpenAPI 3.1 schema that defines the APIs that you want to make available as part of this tool.

Hymalaia provides dynamic context variables that can be utilized within your OpenAPI definition, enhancing the functionality and context-awareness of your custom tools. These variables are:

  • CHAT_SESSION_ID : Replaced with the chat session ID in which the tool call was made.

  • CHAT_MESSAGE_ID : Replaced with the chat message ID which triggered the tool call.

For example: /persona/CHAT_SESSION_ID/messages/CHAT_MESSAGE_ID with CHAT_SESSION_ID = 20 and CHAT_MESSAGE_ID = 10 would become /persona/20/messages/10

​
✅ Tips for Schema Optimization

To ensure smooth integration and performance:

  • Add summaries for each operation
  • Use descriptive operationIds
  • Add parameter descriptions

​
🔧 Example Tool Definition

Here’s an example of a tool schema that enables assistants to fetch and create assistants within Hymalaia:

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Assistants API",
    "description": "An API for managing assistants within Hymalaia"
  },
  "servers": [
    { "url": "http://localhost:8080" }
  ],
  "paths": {
    "/persona": {
      "get": {
        "summary": "Get a specific Assistant",
        "operationId": "getAssistant",
        "parameters": [
          {
            "name": "assistant_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ]
      },
      "post": {
        "summary": "Create a new Assistant",
        "operationId": "createAssistant",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "num_chunks": { "type": "number" },
                  "llm_relevance_filter": { "type": "boolean" },
                  "is_public": { "type": "boolean" },
                  "llm_filter_extraction": { "type": "boolean" },
                  "recency_bias": {
                    "type": "string",
                    "enum": ["favor_recent", "base_decay", "no_decay", "auto"]
                  },
                  "prompt_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "document_set_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "tool_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "llm_model_provider_override": {
                    "type": "string",
                    "nullable": true
                  },
                  "llm_model_version_override": {
                    "type": "string",
                    "nullable": true
                  },
                  "starter_messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": { "type": "string" },
                        "content": { "type": "string" }
                      }
                    },
                    "nullable": true
                  },
                  "users": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "nullable": true
                  },
                  "groups": {
                    "type": "array",
                    "items": { "type": "integer" },
                    "nullable": true
                  }
                },
                "required": [
                  "name", "description", "num_chunks", "llm_relevance_filter",
                  "is_public", "llm_filter_extraction", "recency_bias",
                  "prompt_ids", "document_set_ids", "tool_ids"
                ]
              }
            }
          }
        }
      }
    }
  }
}

🔐 Security Note Make sure that any external API you expose via a custom tool:

  • Has proper authentication/authorization controls

  • Limits the assistant to only the operations you’ve defined

  • Avoids exposing sensitive or destructive endpoints unintentionally