Skip to main content
Version: 2.0

Creating instructions

An agent's behavior is defined by the instructions you give it. The agent uses these instructions alongside information from a conversation session to determine how to respond to user input, including which tools to use.

This section provides information about creating instructions, velocity templates, and some metadata pattern examples.

Note

Instructions in Vectara are referred to as system prompts in other LLM APIs (such as Gemini, Mistral, and OpenAI). If you are familiar with system prompts terminology, instructions serve a similar purpose. Instructions define the role, behavior, and guidelines of an agent before any user interaction begins.

Creating instructions​

To create an instruction, you provide information like name and description, template details, and arbitrary metadata for tracking, versioning, or categorization.

Be specific to exactly what you want the agent to do. For emphasis, use CAPS if you want the agent to follow a specific format. You can also use negative prompts such as saying DO NOT DO ....

See Create Instruction API for detailed specifications.

Using instructions in agents​

When creating or configuring agents, you can use instructions in two ways:

  • Create new instructions in the agent configuration directly:

    INLINE INSTRUCTION IN AGENT

    Code example with json syntax.
    1
  • Reference an existing instruction by name and version:

    REFERENCE INSTRUCTION IN AGENT

    Code example with json syntax.
    1

Use multiple instructions​

Agents can use multiple instructions together that are processed in order. In this example, you have three instructions:

MULTIPLE INSTRUCTIONS

Code example with json syntax.
1

Velocity templates​

Instructions use the [Apache Velocity](Apache Velocity) templating engine, which enables you to dynamically insert variables into your prompts using the tools context and the metadata context.

See the available prompt variables for more information.

Tools context​

$tools is a list of tools available to the agent. You can iterate over tools to display their names and descriptions in your instructions.

TOOLS IN TEMPLATE

Code example with velocity syntax.
1

This dynamically lists all available tools when the agent is initialized.

Metadata context​

Instructions can access metadata from both sessions and agents, enabling personalized and context-aware behavior:

  • ${session.metadata.field} - Access session-specific metadata (user context, permissions, preferences)
  • ${agent.metadata.field} - Access agent-level metadata (version, configuration, environment)
  • ${currentDate} - Current date/time in ISO 8601 format

SESSION METADATA IN TEMPLATE

Code example with velocity syntax.
1

When a session is created with this metadata:

SESSION METADATA

Code example with json syntax.
1

The instruction renders as:

"Hello! I see you're Jane Smith from EMEA. I'm here to help you with billing inquiries. As an enterprise customer, you have access to priority support and advanced features. Your support tier: priority. Preferred language: en"