Instructions
Instructions serve as reusable blocks of system prompt logic. They guide the reasoning and behavior of an agent by setting expectations, prompts, and providing the rules for the underlying Large Language Model (LLM).
Instructions use the Apache Velocity templating engine, which enables you to dynamically insert variables into your prompts. You can configure instructions for an agent in two ways: inline or shared.
Inline Instructions
You define inline instructions when you configure an agent. These instructions are specific to that agent and best for situations that do not require reuse.
- Type: To specify an inline instruction, set the
type
field to"inline"
. - Lifecycle: An inline instruction is automatically deleted if the agent it belongs to is deleted.
1
Shared (Reference) Instructions
You can create shared instructions as independent, versioned entities for reuse across multiple agents. This is ideal for standardizing behavior, such as enforcing brand voice or defining common workflows.
A shared instruction consists of the following:
- A unique ID (
ins_12345
). - A
name
anddescription
. - A
prompt
template. - Optional
metadata
for organization. - A
version
for tracking updates.
To use a shared instruction, set the type
field to "reference"
and provide the instruction's unique id
.
When you update a shared instruction, this creates a new version of that instruction. To use the new version, you must update any agents that reference the instruction. If you do not specify a version, the agent uses the latest one.
1
Template Context
The Velocity templating engine has access to contextual information during execution, such as the results from tool calls. This allows you to create dynamic and responsive instructions. For this version, agent and session context are not included in the template scope.