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.

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 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 examples​

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"

Common metadata patterns​

This section provides some example metadata patterns that you can use in your instructions.

Access control security​

Use metadata to enforce permissions and data access policies:

  • 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, secret) - Enforce document access policies.
  • data_classification (internal, external) - Control what information can be shared.

    ACCESS CONTROL EXAMPLE

    Code example with velocity syntax.
    1

Personalization​

Customize agent behavior based on user preferences:

  • language (en, es, fr) - Respond in the preferred language of the user.
  • timezone (America/New_York) - Schedule meetings and show local times.
  • subscription_tier (free, pro, enterprise) - Enable or disable premium features.
  • user_preference (brief, detailed) - Adjust responses for length or brevity.
  • region (EMEA, APAC, Americas) - Show region-specific content, pricing, compliance.

    PERSONALIZATION EXAMPLE

    Code example with velocity syntax.
    1

Business context​

Provide relevant information based on customer or business attributes:

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

    BUSINESS CONTEXT EXAMPLE

    Code example with velocity syntax.
    1

Workflow routing​

Guide agent behavior based on conversation context:

  • support_tier (L1, L2, escalated) - Route questions to the 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 the agent needs human intervention.
  • channel (web, mobile, API, voice) - Adjust the response format and length.

    WORKFLOW EXAMPLE

    Code example with velocity syntax.
    1

API reference​

For complete API details, see the Instructions API Reference.