Overview
Embed dynamic user context into agent instructions using system variables to create adaptive, personalized responses. This tutorial demonstrates how to automatically insert user details, enabling agents to greet users by name, verify identities, and tailor actions based on individual profiles.
Learning Objectives:
Implement system variables in agent instruction prompts
Configure fallback behaviors for missing user information
Personalize agent interactions while maintaining privacy
Test variable-based instructions across different user scenarios
Prerequisites
You'll Need:
Access to a workspace with agent creation privileges
At least one configured agent
Understanding of JSON syntax (for advanced {{user}} variable usage)
TeamAI API access (optional, for programmatic implementations)
Using System Variables in Agent Instructions
Available System Variables
TeamAI provides these case-sensitive placeholders for agent instructions:
{{user.id}}: Unique TeamAI User ID of the current chatter
{{user.name}}: User's name from their TeamAI account (may be empty)
{{user.email}}: User's email address (may be empty)
{{user}}: Complete user profile as JSON text string (e.g.,
{"id":"teamai-user-xyz","name":"Dana","email":"[email protected]"})
Note: The current date is automatically available to agents without requiring a variable.
Implement Variables in Agent Instructions
Access agent settings:
Navigate to the agents section in the left panel
Click the agent name you want to configure
Scroll to the "Instructions" text box in the agent settings
Add personalized greeting logic:
4. Insert variable placeholders directly into your instruction text:
You are a customer support assistant. Always start by greeting the user. If their name is available, say: "Hello {{user.name}}, welcome to support! How can I help you today?" If the name is not known, use: "Hello! Welcome to support, how can I assist?"
Configure identity verification:
5. Use email variables for confirmation prompts:
When the user asks to make a reservation, confirm: "Okay, I'll make this booking under the email address: {{user.email}}. Is that correct?"
Enable user-specific tool operations:
6. Pass user IDs to custom tools:
If the user asks for their account status, use the 'AccountStatusChecker' tool. Tell the tool to look up the status for user ID {{user.id}}.7. Click "Publish" in the top-right corner to activate changes
Result: The agent now dynamically inserts user data into responses and tool calls.
Decision Table: Variable Selection Guide
Use Case | Recommended Variable | Fallback Strategy |
Personal greetings | {{user.name}} | Generic "Hello" if name empty |
Identity verification | {{user.email}} | Prompt user to provide email |
Account lookups | {{user.id}} | Request manual ID entry |
Advanced conditional logic | {{user}} | Parse JSON and check for null values |
Audit logging | {{user.id}} | Log "anonymous" if ID unavailable |
Using System Variables with the TeamAI API
When calling agents via the TeamAI API (/api/v1/chat), pass system variables in your request body:
API Request Format:
{ "messages": [...], "agentId": "your-agent-id", "systemVariables": { "user": { "id": "user-123", "name": "John Doe", "email": "[email protected]" } }, "variables": { "customVar": "value" } }Optional Fields and Defaults:
systemVariablesandvariablesare both optionalIf omitted, system variables default to:
systemVariables.user.id→"not-provided"systemVariables.user.name→"api-user"systemVariables.user.email→"not-provided"
Custom variables are skipped if not provided
Result: API-initiated chats receive the same personalization as UI-based interactions.
Best Practices
Write natural-sounding instructions: Weave variables into agent instructions conversationally rather than mechanically. The agent should mention user details fluidly.
Always handle missing information: Configure fallback behaviors since
{{user.name}}and{{user.email}}may be empty. Instruct agents to use generic alternatives when data is unavailable.Respect privacy boundaries: Use user information only when relevant to the task. Avoid over-personalization that feels intrusive or unnecessary.
Test multiple scenarios: Verify agent behavior with:
Users who have complete profiles (name, email, ID)
Users with partial information (ID only)
API calls with no system variables provided
Use exact variable syntax: System variables are case-sensitive and require double curly braces.
{{user.id}}works;{{User.ID}}or{{user.id}}without braces fail.Document your variable usage: Maintain a reference of which agents use which variables for easier troubleshooting and team knowledge sharing.
Common Questions
Q: Can I create custom variables beyond the system-provided ones?
A: Yes. Include any custom variables in the variables object in API calls, then reference them as {{customVarName}} in agent instructions.
Q: What happens if I use {{user.name}} but the user hasn't set a name?
A: The variable resolves to an empty string. Always include conditional logic: "If name is available, greet them by name; otherwise, use a generic greeting."
Q: Are system variables available in all agent types?
A: Yes. All agents across Starter, Best-of-Breed, Professional, and Enterprise plans support system variable substitution.
Q: Can agents modify user data through these variables?
A: No. Variables are read-only. Agents cannot change user profiles, only reference the provided information.
Q: How do I debug variable substitution issues?
A: Temporarily add an instruction: "First, repeat the following: User ID is {{user.id}}, Name is {{user.name}}, Email is {{user.email}}." Then test to see what values populate.
Q: Is the {{user}} JSON string safe to parse in instructions?
A: Yes, but it's raw text. For advanced use cases, instruct the agent to parse the JSON and extract specific fields, though this requires careful prompt engineering.
Q: Can I use variables in tool parameter mappings?
A: Yes. When configuring tool inputs in the agent settings, you can map {{user.id}} or other variables directly to tool parameters.