v2

OpenAPI 3.0.02026-08-051996591.2 MB

Instructions

Update instruction

Updates an existing instruction's template, metadata, and configuration. Updated templates may include Velocity variables such as $tools or metadata references. Each update creates a new version. Agents continue to use existing versions until you change them explicitly.

:::info Version Management Agents referencing a specific version continue to use it until updated. Agents without a pinned version always use the latest. :::

Disable an instruction

Use this endpoint to disable an instruction without deleting it.

:::warning Disabling an instruction prevents it from being added to new agents, but agents already using it continue to operate normally. :::

patch/v2/instructions/{instruction_id}

Path parameters

instruction_idstring required

The unique identifier for an instruction.

Example:ins_customer_support_init

The unique identifier of the instruction to update.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

typestring required

The type of instruction to update.

namestring

The human-readable name of an instruction.

descriptionstring

A detailed description of what this instruction does.

templatestring

The instruction template content. How it is rendered depends on the sibling template_type.

When template_type is text, the content is used verbatim as the instruction and no variables are substituted.

When template_type is velocity, the content is rendered with the Velocity engine and the following variables are available:

$agent.name - Agent name
$agent.key - Agent key
$agent.metadata - Agent metadata map
$session.key - Session key
$session.metadata - Session metadata map (includes user-provided context from test/runtime)
$currentDate - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z")
$tools - List of tool maps, each with name and description fields

Example: You are a helpful customer support agent. Agent: $agent.name. Today is $currentDate. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end

template_type'velocity' | 'text'

The templating engine used to render the instruction's template.

velocity: render the template with the Velocity engine, substituting agent, session, and tool variables.
text: use the template verbatim as plain text, with no variable substitution.

metadataobject

Arbitrary metadata associated with the instruction.

enabledboolean

Whether the instruction is enabled.

Example request

{
  "type": "initial",
  "name": "Customer Support Initial Instruction",
  "description": "Enhanced initial context and guidelines for customer support interactions",
  "template": "You are an expert customer support agent for $agent.name. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end",
  "template_type": "velocity",
  "metadata": {
    "version": "1.1.0",
    "author": "support-team",
    "last_reviewed": "2024-01-15"
  },
  "enabled": true
}

Response

The updated instruction.

idstring required

The unique identifier for an instruction.

typestring required

The type of instruction.

namestring required

The human-readable name of an instruction.

descriptionstring

A detailed description of what this instruction does.

template_type'velocity' | 'text' required

The templating engine used to render the instruction's template.

velocity: render the template with the Velocity engine, substituting agent, session, and tool variables.
text: use the template verbatim as plain text, with no variable substitution.

templatestring required

The instruction template content. How it is rendered depends on the sibling template_type.

When template_type is text, the content is used verbatim as the instruction and no variables are substituted.

When template_type is velocity, the content is rendered with the Velocity engine and the following variables are available:

$agent.name - Agent name
$agent.key - Agent key
$agent.metadata - Agent metadata map
$session.key - Session key
$session.metadata - Session metadata map (includes user-provided context from test/runtime)
$currentDate - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z")
$tools - List of tool maps, each with name and description fields

Example: You are a helpful customer support agent. Agent: $agent.name. Today is $currentDate. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end

versioninteger required

The version identifier for this instruction. The version increments automatically when the instruction is updated.

metadataobject

Arbitrary metadata associated with the instruction.

enabledboolean required

Whether the instruction is currently enabled and available for use.

created_atstring date-time

Timestamp when the instruction was created.

updated_atstring date-time

Timestamp when the instruction was last updated.

Example response

{
  "id": "ins_customer_support_init",
  "type": "initial",
  "name": "Customer Support Initial Instruction",
  "template_type": "velocity",
  "template": "You are an expert customer support agent for $agent.name. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end",
  "version": 1
}