Skip to main content
Version: 2.0

Instructions

Create and manage instructions that guide agent behavior. The agent uses these instructions alongside information from a conversation session to determine how to respond to user input, including which tools to use.

Note

Instructions in Vectara are referred to 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.

Templating​

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. The available context variables include:

Tools​

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

Example usage in templates:

You have access to the following tools:
#foreach($tool in $tools)
  - ${tool.name}: ${tool.description}
#end

Metadata​

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).

Session metadata examples​

Consider the following session metadata examples:

Access Control & Security​

  • user_role (admin, manager, employee): Filter search results by permission level.
  • tenant_id (company123): Isolate data in multi-tenant systems.
  • department (legal, sales, engineering): Show only relevant documents.
  • clearance_level (public, confidential): Enforce document access policies.
  • data_classification (internal, external): Control what information can be shared.

Personalization​

  • language (en, es, fr): Respond in user's preferred language.
  • timezone (America/New_York): Schedule meetings, show local times.
  • subscription_tier (free, pro, enterprise): Enable/disable features.
  • user_preference (brief, detailed): Adjust response verbosity.
  • region (EMEA, APAC, Americas): Show region-specific content, pricing, compliance.

Business Context​

  • customer_id (cust_789): Pull customer-specific orders, support history.
  • account_type (trial, paid, enterprise): Customize onboarding experience.
  • industry (healthcare, finance): Use industry-specific terminology.
  • product_owned (basic, premium): Provide relevant help documentation.
  • contract_type (annual, monthly, perpetual): Tailor renewal reminders.

Workflow & Routing​

  • support_tier (L1, L2, escalated): Route to appropriate knowledge base.
  • conversation_type (sales, support, onboarding): Apply different tones and approaches.
  • agent_purpose (billing, technical, general): Focus search on relevant corpora.
  • escalation_needed (true/false): Track when to hand off to human.
  • channel (web, mobile, API, voice): Adjust response format and length.

Metadata usage example​

"template": "Hello! I see you're ${session.metadata.user_name} from ${session.metadata.region}. I'm here to help you with ${session.metadata.department} inquiries."

When a session is created with this metadata:

{
  "metadata": {
    "user_name": "John Doe",
    "region": "NA",
    "department": "billing"
  }
}

The instruction renders as:

"Hello! I see you're John Doe from North America. I'm here to help you with billing inquiries."

Last updated on by Paul Wozniczka