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

Instructions are one of the most critical parts of an agent's design. Best practices vary by model, but at a minimum you should provide clear guidance on what tools are available, what output format is desired, and what steps to follow for common queries. Instructions typically need to be iterated on and tested 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 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