Make your TeamAI Agents more aware and adaptive by using System Variables in their instructions. These variables let you automatically include details about the current user or the date, helping your Agent tailor its responses and actions.
Understanding System Variables in Agent Instructions
When you define how an Agent should behave (its "instructions"), you can embed placeholders for system variables. When a user interacts with the Agent, TeamAI replaces these placeholders with the actual information relevant to that specific user and interaction.
Available System Variables for Agent Instructions:
{{user.id}}: Inserts the unique TeamAI User ID of the person currently chatting with the Agent.
{{user.name}}: Inserts the name associated with the user's TeamAI account (if their name is available).
{{user.email}}: Inserts the email address associated with the user's TeamAI account (if their email is available).
{{user}}: Inserts a complete package of the user's TeamAI information as a JSON text string (e.g.,{"id":"teamai-user-xyz","name":"Dana","email":"[email protected]"}). This can be useful for more complex conditional logic within the Agent's instructions if needed for advanced scenarios.
(Note on Date: Good news! For Agents, the current date is automatically available to them. You don't need to add a {{DATE}} variable in your instructions like you might for Custom Plugins; your Agent will already know today's date.)
Example Uses in Agent Instructions:
Personalized Greetings and Interactions:
Make your Agent more friendly and personal by having it address the user by their name.
Agent Instruction Example (scroll left to right):
You are a customer support assistant. Always start the conversation 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 a general greeting like: 'Hello! Welcome to support, how can I assist?'
Setting Context for Agent Actions:
Use system variables to give the Agent context about the user before it performs a task or uses a tool.
Agent Instruction Example (scroll left to right)
You are a booking assistant. When the user asks to make a reservation, confirm their identity by stating: 'Okay, I can help with that. I'll make this booking under the email address: {{user.email}}. Is that correct?'
User-Specific Information Retrieval (with appropriate tools):
If an Agent uses a tool that can look up information based on a TeamAI User ID (perhaps a custom tool you've built), the Agent's instructions can guide this.
Agent Instruction Example (scroll left to right)
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}}.
Conditional Behavior based on User Details (Advanced):
For more complex scenarios, you could (carefully) instruct an Agent to act differently based on user attributes.
Agent Instruction Example (scroll left to right) (Conceptual):
Your primary role is to provide general information. However, if the user's details {{user}} indicate they are part of a 'premium_member' group (this would require your system to interpret the {{user}} JSON string or for the JSON string to contain such a flag), then you can also offer access to exclusive articles using the 'PremiumContent' tool.Using System Variables with the TeamAI API
When calling your Agents through the TeamAI API (/api/v1/chat), you can pass system variables and custom variables in your request to enable the same personalization available in the TeamAI UI.
API Request Format
Include systemVariables and variables in your request body:
{
"messages": [...],
"agentId": "your-agent-id",
"systemVariables": {
"user": {
"id": "user-123",
"name": "John Doe",
"email": "[email protected]"
}
},
"variables": {
"customVar": "value"
}
}What's Optional
Both the system variables and variables fields are optional - if not provided, defaults are used for system variables and variables are skipped
systemVariables.user.id → defaults to "not-provided"
systemVariables.user.name → defaults to "api-user"
systemVariables.user.email → defaults to "not-provided"
variables → can include any custom variables for your agent instructions
Best Practices for Using System Variables in Agents:
Natural Language: Weave the variables into your Agent's instructions in a way that sounds natural for how you want the Agent to think or speak.
Handle Missing Information: Remember that {{user.name}} or {{user.email}} might not always be available. Instruct your Agent on how to behave in such cases (e.g., use a generic greeting).
Privacy and Relevance: Only use user information in a way that is helpful and relevant to the Agent's task and the user's interaction. Avoid over-personalization that might feel intrusive.
Testing: Always test your Agent with different user scenarios (including users where some information might be missing) to ensure it behaves as expected.
Exact Naming: System variables are case-sensitive (e.g., {{user.id}} is correct, {{User.ID}} is not).
Double Curly Braces: Ensure variables are enclosed in {{ }}.
By using system variables, you can make your Agents more context-aware, leading to more efficient, personalized, and helpful conversations.