---
title: "Create instruction"
method: POST
path: "/v2/instructions"
tags: ["Instructions"]
---

# 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:
```velocity
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:
- [Claude Prompt Engineering](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview)
- [OpenAI Prompt Engineering](https://platform.openai.com/docs/guides/prompt-engineering)
:::

Metadata can personalize behavior at runtime. For example:

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

**Example request:**
```json
{
  "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.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreateInstructionRequest — Base properties for creating an instruction, without the type discriminator field.
  - `name` string, required — The human-readable name of an instruction.
  - `description` string — 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.
  - `template` string, 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`
  - `metadata` object — Arbitrary metadata associated with the instruction.
  - `enabled` boolean — Whether the instruction should be enabled upon creation.
  - `type` string, required — The type of instruction to create.

## Response `201`

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

- Instruction — An initial instruction that provides guidance to the agent before user messages.
  - `id` string, required — The unique identifier for an instruction.
  - `type` string, required — The type of instruction.
  - `name` string, required — The human-readable name of an instruction.
  - `description` string — 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.
  - `template` string, 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`
  - `version` integer, required — The version identifier for this instruction. The version increments automatically when the instruction is updated.
  - `metadata` object — Arbitrary metadata associated with the instruction.
  - `enabled` boolean, required — Whether the instruction is currently enabled and available for use.
  - `created_at` string, date-time — Timestamp when the instruction was created.
  - `updated_at` string, date-time — Timestamp when the instruction was last updated.

## Other responses

- `400` — Instruction creation request was malformed or contains invalid content.
- `403` — Permissions do not allow creating instructions.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/83554494d7f8/schema)