Adding instructions

Edit online

AI agents operate based on instructions that define how they respond to users, perform tasks, and interact with tools or other agents. These instructions act as behavioral guidelines, helping ensure consistent, reliable, and brand-aligned responses across all interactions.

You can configure instructions in the Behavior section of the agent configuration page. Once saved, they are applied globally across all tasks and channels, meaning that the agent follows them regardless of where or how it is called.

Steps to add instructions

To define or update your agent's behavior:

  1. From the main menu, go to Build.

  2. Click Create agent > Create from scratch.

  3. Enter a Name and Description.

  4. Go to the Behavior section.

  5. In the Instructions field, add simple rules such as:
    • Use a polite and professional tone
    • Summarize user requests before responding
    • Escalate unresolved issues
  6. Test your agent in chat to validate behavior.

  7. Review Recommendations for writing effective instructions first. It’s essential to help ensure that your agent behaves as expected.

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

Instructions are configurable rules that shape how your agent behaves. They determine:

  • How the agent responds to user input
  • When tools or workflows are triggered
  • How the agent collaborates with other agents
  • Tone, style, and boundaries of communication

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

How instructions work

Before you add instructions to the agent, it’s important to understand how they work and what impact they have:

Important considerations

  • Global scope: Instructions apply to all channels (for example, chat or Slack) and all agent tasks. Currently, you cannot set conditional instructions based on user context, channel, or task type.

  • Immediate effect: Changes are saved automatically and applied instantly.

  • Overwrite behavior: New instructions replace all previously defined instructions. Versioning or rollback is not supported.

  • Default behavior If no instructions are defined, the agent uses its built-in logic. While it can work for general use cases, it might not align with your specific business needs.

Note:

If your instructions start to include many conditions, branches, or sequences, consider using an agentic flow. Workflows help you codify complex logic into a structured, repeatable format that’s easier to manage and scale. For detailed information, see Agentic workflows.

Customizing agent responses with context variables

Context variables allow your agent to generate dynamic, personalized responses using values such as user name, email, or location.

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.

Use agentic workflows effectively

When invoking an agentic workflow, ensure the agent is properly configured to read context variables and interpret workflow outputs correctly. To do this, add the following instructions.

Example agent instructions:

  • When invoking agentic workflow, do not reconstruct the final sentence or output from the input parameters. Instead:
  • Capture the exact response returned by the flow.
  • If the response is a plain string, return it to the user unchanged.
  • If the response is a JSON object, extract the relevant field values and include them in the final message.
  • Only add additional explanatory text after the workflow output, and do not replace the workflow-generated output.
  • Ensure the output strictly conforms to the JSON schema defined in <output_schema>{self.spec.output_schema}</output_schema>, and do not include any text outside the JSON object.
  • Provide schema references and example outputs (for example, routing or structured responses) to improve the model's accuracy and consistency in generating correct workflow outputs.
  • Example output (Routing to Billing Agent): 
    
{  
"steps_taken": ["Analyzed user intent.", "Classified as Billing issue."],  
"final_solution": "",  
"current_status": "Routing to Billing Agent.",  
"next_agent": "billing_agent",  
"next_agent_instruction": "Customer reports double charge. Investigate transaction ID X and issue refund."
}

These practices ensure that workflow outputs are passed accurately to users.

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.

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

Does not support 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.

  • 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 agents.

  • Review and update the instructions regularly to reflect changes in your business goals, user expectations, or supported tasks.