Skip to main content
Version: 2.0

Instructions

An agent's behavior is defined by the instructions you provide. 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.

Writing good instructions​

To write good instructions, specify exactly what you want the agent to do.

  • Use CAPS for emphasis, if you want the agent to follow a specific format.
  • Use negative prompts like DO NOT DO this or that, if you want the agent to avoid any thing.

Agents can also use multiple instructions together that process in order. See the Create Instruction API for more details.

Inline vs reference instructions​

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

Create dynamic instructions with Velocity templates​

Instructions use the 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"