Adding instructions to agents
AI agents operate based on a set of behavioral instructions that define how they respond to user inputs, perform tasks, and interact across different channels. These instructions serve as the agent’s internal guidelines, helping it act consistently and effectively in various scenarios.
By configuring these instructions, you can ensure that the agent aligns with your organization’s tone, business objectives, and user expectations. Whether the agent is answering a question, triggering a tool, or collaborating with another agent, these rules help maintain a seamless and professional experience.
Instructions are added in the Behavior section of the Agent Builder. Once added, they are applied globally across all channels and tasks, meaning that the agent follows them regardless of where or how it is called.
What are instructions
Instructions are configurable rules that shape the agent’s behavior. They determine how the agent responds, when it triggers tools, and how it collaborates with other agents. Instructions are added in the Behavior section of the Agent Builder and apply globally across all channels and tasks.
When to use instructions
Use instructions when you want to:
- Align the agent’s tone with your brand.
- Control how the agent handles specific scenarios.
- Ensure consistent behavior across channels and tasks.
- Enable collaboration with tools or other agents.
Before you begin
Before you add instructions to the agent, it’s important to understand how they work and what impact they have:
-
Instructions overwrite existing ones: When you enter new instructions, they replace any previously defined rules. Versioning or rollbacks are not supported, so review changes carefully before you save.
-
Changes are saved automatically: When you enter or modify instructions, they’re applied instantly.
-
Defaults apply when instructions are missing: If you leave the instructions field blank, the agent relies on its built-in logic. While it can work for general use cases, it might not align with your specific business needs.
-
Instructions apply globally: Any instruction that you add is applied across all channels (for example, chat, Slack) and all tasks the agent performs. Currently, you cannot set conditional instructions based on user context, channel, or task type.
Steps to add instructions
To define or update your agent’s behavior:
- From the main menu, go to Build.
- Click Create agent > Create from scratch.
- Enter a Name and Description.
- Go to the Behavior section.
- In the Instructions field, enter clear and actionable rules.
Review Recommendations for writing effective instructions first. It’s essential to help ensure that your agent behaves as expected. - Changes are saved automatically.
When instructions are added, the agent begins by using them right away in all conversations. These rules influence how the agent responds to user request, across all tasks and connected channels.
Customizing agent responses with context variables
AI agents can tailor responses based on the user they're interacting with and the information already available. Context variables enable dynamic, personalized replies that reflect the current situation and user profile.
The context variables act like placeholders for user-specific data, such as email ID, location, or membership ID that you can pass into the agent’s behavior. With them, your agent becomes more intelligent, responsive, and relevant.
Benefits of using context variables
- Personalized responses: Greet users by name, refer to their location, or tailor answers based on their role or preferences.
- Session continuity: Carry information across multiple steps or tasks without asking the user to repeat themselves.
- Smarter integrations: Share user data with tools or other agents to perform actions like fetching records or triggering workflows.
How to set it up
To use context variables, you must first define them by using the Agent Development Kit (ADK). The ADK provides a way to specify the type of data your agent recognizes and how to access it. For more information, see Providing access to context variables.
How to use them in instructions
Once your variables are defined in the ADK, you can reference them directly in the Behavior section of the Agent Builder by using curly braces {}.
The following are sample instructions that use context variables:
- Always respond with watsonx Orchestrate email ID as {wxo_emailid}, wxo user name as {wxo_userid}, wxo tenant ID as {wxo_tenantid}, location as {location}, and member ID as {memberid}.
- Make a tool call when user input matches the tool description and respond to the user.
- Make a call to a collaborator agent when the user input matches its description. Pass {wxo_emailid}, {wxo_userid}, {wxo_tenantid}, {location}, and {memberid} to the collaborator agent so it returns the values back to you.
Recommendations for writing effective instructions
When you write instructions for your AI agent, it's important to follow clear and effective guidelines that ensure the agent behaves consistently, professionally, and in alignment with your business goals. Well-defined instructions shape how the agent responds to users, handles tasks, and maintains a professional tone across all interactions.
The following are categorized recommendations for writing effective instructions and avoiding common mistakes.
What to do
| Category | Recommended instruction |
|---|---|
| Be specific | "Escalate unresolved issues to a human agent." "Use a polite tone in all responses." "Ask for clarification if the request is vague." |
| Focus on behavior | "Don't make assumptions if the user’s intent is unclear." "Summarize long responses when possible." |
| Define boundaries | "Do not give legal, financial, or medical advice." |
These instructions help the agent stay on track, maintain a professional tone, and avoid overstepping its role.
What to avoid
| Category | Recommended instruction |
|---|---|
| Don’t be vague | "Always try your best" "Be helpful" "Be friendly" (unless part of a task, like a greeting) |
| Don’t use unsupported logic | "Only respond this way if the user sounds confused" "Adjust tone based on user emotion" |
| Don’t include conflicting rules | "Keep responses short" + "Always provide detailed answers" |
Avoid vague or contradictory instructions, as they can confuse the agent and lead to inconsistent behavior.
Example for effective agent instructions
Use the following example as a reference when defining your own agent behavior. The sample illustrates how to write clear, goal-oriented, and brand-aligned instructions that help your agent respond accurately.
Example: IT support agent
The following sample instructions define the behavior of a technical support agent that helps users troubleshoot system or environment issues, manage tickets, and provide configuration guidance.
- Always greet the user courteously. Include their name if available.
Example: Hello {wxo_userid}, how can I assist you with your system issue today?
- Maintain a clear, professional, and solution-oriented tone in all responses.
- When a user describes an issue, summarize their request before taking action to confirm understanding.
Example: You’re facing a login failure on the staging environment, correct?
- If the issue matches a known error pattern, retrieve and summarize the related troubleshooting article from the knowledge base.
- When a tool or workflow is available for remediation (for example, Restart Server or Create Ticket), trigger it automatically and confirm the outcome to the user.
- Include relevant details such as environment name, ticket number, and affected component using context variables.
- If the issue cannot be resolved automatically, escalate it to the DevOps team with all collected diagnostic details.
- Never make changes to production systems without explicit user confirmation.
Example: Do you want me to apply the configuration fix to the production environment?
- Close the conversation by confirming resolution or next steps.
Example: Your ticket {ticket_id} has been created. The DevOps team will review it shortly.
What to do next
When you finish adding instructions, take the following steps to validate and refine your agent’s behavior:
- Test your agent in the chat page to observe how it applies the new instructions.
- Connect your agent to a supported channel (for example, Slack, Microsoft Teams) to evaluate responses in real-world scenarios. For more information, see Connecting to channels.
- Deploy your agent. For more information, see Deploying the agent.
- Review and update the instructions regularly to reflect changes in your business goals, user expectations, or supported tasks.