Function-calling quickstart: OpenAI-style and Hermes agents

Any model that supports function calling (tool calling) can control ai-supply with two function definitions. This guide provides copy-paste schemas and the matching HTTP calls.

These schemas work with OpenAI-style function calling (GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo) and Hermes-style function calling (Nous Hermes 2, OpenHermes, Hermes 3, and any model trained on the Hermes function-calling format). The JSON schema is identical — both formats accept the same parameters object.

Function schemas

Pass this array as the tools (OpenAI) or functions (Hermes) field in your model call:

[
  {
    "type": "function",
    "function": {
      "name": "search_ai_supply",
      "description": "Search ai-supply.store catalog for AI capabilities. Returns a list of matching listings with slug, name, kind, pricingModel, rating, and securityScore.",
      "parameters": {
        "type": "object",
        "properties": {
          "q": {
            "type": "string",
            "description": "Keyword search query, e.g. 'web search' or 'code execution'."
          },
          "kind": {
            "type": "string",
            "description": "Capability type to filter by. Common values: MCP, API, Agent, Dataset, Model."
          },
          "category": {
            "type": "string",
            "description": "Category slug to filter by."
          },
          "price": {
            "type": "string",
            "enum": ["free", "paid"],
            "description": "Filter and sort the catalog."
          },
          "sort_by": {
            "type": "string",
            "enum": ["installs", "rating", "security_score"],
            "description": "Sort results by install count, average rating, or security score."
          }
        },
        "required": []
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "install_ai_supply",
      "description": "Install a listing from ai-supply.store by its slug. Records ownership in the agent's account. Must be called before download_ai_supply.",
      "parameters": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "The unique slug of the listing to install, e.g. 'web-search-mcp'."
          }
        },
        "required": ["slug"]
      }
    }
  }
]

Executing the function calls

When the model emits a tool_call (or Hermes <tool_call> block), map the function name to these HTTP calls:

search_ai_supply

import requests, os

def search_ai_supply(q="", kind="", category="", price="", sort_by=""):
    params = {k: v for k, v in
              {"q": q, "kind": kind, "category": category,
               "price": price, "sort_by": sort_by}.items() if v}
    resp = requests.get(
        "https://ai-supply.store/api/v1/listings",
        headers={"Authorization": f"Bearer {os.environ['AIM_API_KEY']}"},
        params=params,
    )
    return resp.json()

install_ai_supply

def install_ai_supply(slug):
    resp = requests.post(
        f"https://ai-supply.store/api/v1/listings/{slug}/install",
        headers={"Authorization": f"Bearer {os.environ['AIM_API_KEY']}"},
    )
    return resp.json()

OpenAI example

from openai import OpenAI
import json

client = OpenAI()
tools = [...]  # the two schemas above

messages = [{"role": "user", "content": "Find a free MCP web-search capability and install it."}]
resp = client.chat.completions.create(model="gpt-4o", tools=tools, messages=messages)

# Execute any tool calls the model returned
for tc in resp.choices[0].message.tool_calls or []:
    args = json.loads(tc.function.arguments)
    if tc.function.name == "search_ai_supply":
        output = search_ai_supply(**args)
    elif tc.function.name == "install_ai_supply":
        output = install_ai_supply(**args)
    messages.append({"role": "tool", "tool_call_id": tc.id, "content": json.dumps(output)})

Hermes-style example

Hermes models (Nous Hermes 2, Hermes 3) parse the same JSON schema. Pass the tools array in your system prompt or via the tools field if your inference server supports it:

# Using an OpenAI-compatible Hermes endpoint (e.g., via llama.cpp or vLLM)
client = OpenAI(base_url="http://localhost:8080/v1", api_key="not-used")
resp = client.chat.completions.create(
    model="hermes-3-llama-3.1-8b",
    tools=tools,
    messages=[{"role": "user", "content": "Find a free data-fetching MCP and install it."}],
)
# Tool call handling is identical to the OpenAI example above.

Key points

• Any function-calling model can use these schemas without modification.
• Set AIM_API_KEY in your environment — see API key guide.
• Extend the pattern with download_ai_supply (GET /api/v1/listings/{slug}/download) to retrieve the artifact after installing.
• Browse what's available at /agents.