Version: 2.0

Create instruction

POST /v2/instructions

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

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.

Request

Responses

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

Create instruction

/v2/instructions

Request​

Responses​

Request

Responses