onyx_custom_tool (Resource)

A custom action: an external HTTP API, described by an OpenAPI schema, that assistants can call.

Attach one to an assistant through tool_ids on onyx_persona.

~> Deleting an action detaches it from every agent that uses it, including agents Terraform does not manage. Onyx does not refuse the delete or warn about it.

~> custom_headers holds secrets and Onyx returns them in full. Anyone who can read the deployment's actions can read the values, and they are stored in Terraform state in clear text. Supply them from a secret store rather than literals.

Example Usage

terraform

# A custom action lets an assistant call an external HTTP API. Onyx derives one
# callable method per operation, so every operation needs an operationId and
# either a summary or a description.
resource "onyx_custom_tool" "weather" {
  name        = "weather"
  description = "Looks up the current weather for a city"

  definition = jsonencode({
    openapi = "3.0.0"
    info = {
      title       = "Weather"
      description = "Current conditions by city"
    }
    servers = [{ url = "https://api.example.com" }]
    paths = {
      "/weather/{city}" = {
        get = {
          operationId = "getWeather"
          summary     = "Get the current weather for a city"
          parameters = [{
            name     = "city"
            in       = "path"
            required = true
            schema   = { type = "string" }
          }]
          responses = { "200" = { description = "Current conditions" } }
        }
      }
    }
  })

  # Sent with every call the action makes. These are secrets: keep them out of
  # the configuration itself and out of version control.
  custom_headers = {
    "X-Api-Key" = var.weather_api_key
  }
}

# Reading the definition from a file keeps a large schema out of the
# configuration.
resource "onyx_custom_tool" "billing" {
  name       = "billing"
  definition = file("${path.module}/openapi/billing.json")

  # Forward the calling user's Onyx credentials instead of a fixed key, so the
  # API applies that user's own permissions. It cannot be combined with an
  # Authorization header above.
  passthrough_auth = true
}

# An action can be turned off without being deleted, which leaves it configured
# but stops any assistant from calling it.
resource "onyx_custom_tool" "legacy_lookup" {
  name       = "legacy-lookup"
  definition = file("${path.module}/openapi/legacy.json")
  enabled    = false
}

Schema

Required

definition (String) The OpenAPI schema describing the API, as JSON. Onyx derives one callable method per operation, so every operation needs an operationId. Use jsonencode(...) or file(...) to supply it.
name (String) Action name, shown to admins and to the model.

Optional

custom_headers (Map of String, Sensitive) Headers sent with every call the action makes, such as an API key. Cannot carry an Authorization header while passthrough_auth is enabled.
description (String) What the action does.
enabled (Boolean) Whether assistants may call the action. A disabled action keeps its configuration but never runs.
oauth_config_id (String) Id of an OAuth configuration the action authenticates with. OAuth configurations are created in the admin panel; Terraform does not manage them yet.
passthrough_auth (Boolean) Forward the calling user's Onyx credentials to the API instead of using a fixed credential. Use it when the API enforces per-user permissions.

Read-Only

display_name (String) Name shown in the chat UI. Onyx derives it from name.
id (String) Numeric action id.

Import

Import is supported using the following syntax:

The terraform import command can be used, for example:

shell

#!/bin/sh
# Import by numeric action id.
terraform import onyx_custom_tool.weather 7

generated by https://github.com/hashicorp/terraform-plugin-docs