onyx_persona (Resource)

An agent (assistant): a named set of instructions, knowledge and actions that users can chat with.

Agent names are unique. Creating one under a name another agent already holds fails; creating one under the name of a deleted agent revives that agent instead, keeping its original id.

~> Deleting an agent leaves a tombstone. Onyx marks it deleted rather than removing the row, so the name stays taken. Creating an agent under that name later revives the tombstone, which is why a destroy followed by an apply returns the same agent id.

Example Usage

# An agent (assistant) pairs instructions with the knowledge and actions it may
# use. Agent names are unique across the deployment.
resource "onyx_persona" "support" {
  name        = "Support"
  description = "Answers customer questions from the handbook"

  system_prompt = <<-EOT
    You are a support agent. Answer from the handbook only.
    If the handbook does not cover the question, say so and offer to escalate.
  EOT

  # Appended to each user message.
  task_prompt = "Cite the handbook section you used."

  document_set_ids = [onyx_document_set.handbook.id]
  tool_ids         = [onyx_custom_tool.weather.id]

  starter_messages = [
    {
      name    = "Refunds"
      message = "How do refunds work?"
    },
    {
      name    = "Shipping"
      message = "How long does shipping take?"
    },
  ]
}

# An agent that only its group may use, kept out of the assistant list.
resource "onyx_persona" "hr_private" {
  name          = "HR"
  description   = "Answers policy questions for the HR team"
  system_prompt = "You answer HR policy questions."

  document_set_ids = [onyx_document_set.hr_private.id]

  # A hidden agent still works for anyone holding a link to it.
  is_listed = false

  # Private agents need Enterprise Edition. Group and user ids come from the
  # deployment, so read them from the admin panel or pass them in.
  is_public = false
  groups    = [4]
  users     = [var.hr_lead_user_id]
}

# Onyx promotes a featured agent to users. Ignoring documents from before a
# migration keeps an agent off stale material.
resource "onyx_persona" "onboarding" {
  name          = "Onboarding"
  description   = "Walks new starters through their first week"
  system_prompt = "You help new employees get set up."

  document_set_ids  = [onyx_document_set.handbook.id]
  is_featured       = true
  display_priority  = 1
  icon_name         = "user"
  search_start_date = "2026-01-01"
}

Schema

Required

• name (String) Agent name. Must be unique across the deployment.

Optional

• datetime_aware (Boolean) Tell the agent the current date and time.
• default_model_configuration_id (String) Id of the model configuration the agent uses. Leave unset to use the deployment default.
• description (String) One line describing the agent, shown on its card.
• display_priority (Number) Sort position in the assistant list. Lower sorts first. Onyx reads this from the agent only when it is created, so a later change is applied through its own endpoint as a second call. Removing the attribute leaves the last value in place rather than clearing it.
• document_set_ids (Set of String) Ids of the document sets the agent can search, e.g. [onyx_document_set.handbook.id].
• groups (Set of Number) User group ids that may use the agent when it is not public. Enterprise Edition only.
• icon_name (String) Name of the built-in icon shown on the agent's card.
• is_featured (Boolean) Whether Onyx promotes the agent to users. Requires agent-management permission.
• is_listed (Boolean) Whether the agent appears in the assistant list. A hidden agent still works for anyone holding a link to it. Onyx sets this through its own endpoint, so Terraform applies it as a second call after the agent is written.
• is_public (Boolean) Whether every user can use the agent. When false, only users and groups can.
• label_ids (Set of Number) Ids of the labels the agent is filed under. Labels are created in the admin panel.
• replace_base_system_prompt (Boolean) Use system_prompt on its own instead of adding it to Onyx's base prompt. Replacing the base prompt drops the instructions that make citations and search work, so leave it off unless the agent needs full control.
• search_start_date (String) Ignore documents older than this date, as YYYY-MM-DD or a full timestamp.

~> Onyx does not return this field, so Terraform cannot detect a change made outside it. The configured value is re-sent on every apply.

• starter_messages (Attributes List) Suggested opening prompts, shown in the order given. (see below for nested schema)
• system_prompt (String) The agent's instructions, added to the system prompt.
• task_prompt (String) Extra instructions appended to each user message.
• tool_ids (Set of String) Ids of the actions the agent can call, e.g. [onyx_custom_tool.weather.id]. Onyx keeps two built-in actions out of its own API responses, so attaching one of those produces a permanent difference; attach custom actions and the ordinary built-ins instead.
• users (Set of String) User ids (UUIDs) that may use the agent when it is not public. Enterprise Edition only.

Read-Only

• builtin_persona (Boolean) Whether Onyx ships the agent as a built-in. Built-in agents are configured in the deployment, not through the API.
• id (String) Numeric agent id.

<a id="nestedatt--starter_messages"></a>

Nested Schema for starter_messages

Required:

• message (String) Message sent when the user picks it.
• name (String) Short label shown on the button.

Import

Import is supported using the following syntax:

The terraform import command can be used, for example:

#!/bin/sh
# Import by numeric agent id.
terraform import onyx_persona.support 4