Version: 2.0

Create instruction

POST /v2/instructions

Supported API Key Type:

Personal

Create a new instruction that defines how an agent should behave, reason, and respond. 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

Provide clear, directive language in the template to shape the agent’s behavior. You can emphasize specific requirements using capital letters or negative instructions such as DO NOT.

Metadata can personalize behavior. 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. ALWAYS be polite and DO NOT USE technical jargon.",
  "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 response includes 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