v2

latestOpenAPI 3.0.02026-08-051996591.2 MB

Instructions

Create instruction

Creates an instruction that defines how an agent behaves, reasons, and responds. Instructions act as system-level guidelines that shape the agent's tone, style, constraints, and tool usage.

Instructions support dynamic content using the Apache Velocity templating engine. Velocity variables allow instructions to reference runtime context:

\$\tools: The list of tools available to the agent.
\$\{session.metadata.field}: Session-level metadata (user context, permissions, preferences).
\$\{agent.metadata.field}: Agent-level metadata (configuration or environment).

Example tool iteration:

You have access to the following tools:
\#foreach(\$\tool in $tools)
  - \$\{tool.name}: \$\{tool.description}
#end

:::tip Tips for effective instruction design Instructions are one of the most critical parts of an agent's design. Best practices vary by model. At a minimum, provide clear guidance on:

The tools that are available.
The desired output format.
The steps to follow for common queries.

Instructions typically need iteration and testing over time.

For guidance on writing effective instructions, see:

Metadata can personalize behavior at runtime. For example:

Hello ${session.metadata.user_name}, how can I help with ${session.metadata.department} today?

Example request:

{
  "name": "Customer Support Tone and Style Guide",
  "description": "Defines tone and behavior for customer interactions.",
  "template": "You are a customer support agent for the ${session.metadata.department} department.",
  "enabled": true,
  "metadata": {
    "owner": "customer-support-team",
    "version": "1.0.0"
  }
}

A successful response returns the full instruction definition, including its unique ID, version, and timestamps.

post/v2/instructions

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

namestring required

The human-readable name of an instruction.

descriptionstring

A detailed description of what this instruction does.

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.

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

metadataobject

Arbitrary metadata associated with the instruction.

enabledboolean

Whether the instruction should be enabled upon creation.

typestring required

The type of instruction to create.

Example request

{
  "name": "Customer Support Initial Instruction",
  "description": "Provides initial context and guidelines for customer support interactions",
  "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",
  "metadata": {
    "version": "1.0.0",
    "author": "support-team"
  },
  "enabled": true,
  "type": "initial"
}

Response

The full definition of the newly created instruction, including fields such as id, version, created_at, and updated_at.

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
}