Adding instructions to agents

The behavior of the AI agent defines how it responds to user requests and situations. You can configure rules that dictate when and how the agent must act. These rules help the agent behave in a predictable and consistent manner, delivering a seamless user experience.

Before you begin

See the following information that can impact the instructions for your agent.

  • When you add new instructions, they overwrite any existing instructions.
  • Changes are saved automatically.
  • If you leave the field empty, the agent uses only its built-in behavior, which might not always match your requirements.
  • Instructions are applied through all channels and tasks. You cannot currently apply them conditionally or based on user context.

Procedure

Follow the steps to add instructions to your agent:

  1. Open your agent in the agent builder.
  2. Go to the Behavior section.
  3. In the Instructions field, enter the rules or behaviors your agent should follow.
  4. Changes are saved automatically.

What happens next

The agent immediately uses the new instructions during conversations and applies the instructions to every request, through all tasks and connected channels.

What to do next

Take the following actions to test and maintain the effectiveness of the agent's instructions:

  • Test your agent in the chat panel to observe how it applies the new behavior.
  • Connect your agent to a supported channel to evaluate responses in a real-world setting.
  • Update the instructions regularly to reflect changes in your goals or processes.

Using context variables in agent instructions

Context variables enable you to pass custom user information to your agent. These variables help the agent give personalized responses and run more complex tasks. For example, you can pass user-specific data like email ID, location, or member ID into the agent’s behavior.

Using context variables you can:

  • Personalize agent responses based on the user’s identity or preferences.
  • Maintain continuity across different tasks or interactions in a session.
  • Share relevant user information with tools or collaborator agents to perform actions.
Note: To define and enable access to context variables, use the Agent Development Kit (ADK). For more information, see Providing access to context variables.

After you define context variables in the ADK, you can provide usage instructions in the Behavior section of the agent builder UI. These instructions guide the agent on how to use the variables during interactions.

Use curly braces {} to reference each variable by name. The following is a sample instruction that uses 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.

Best practices

Follow the best practices of what to do and what to avoid to write instructions that help your agent perform reliably.

What to do

Be specific

Green check icon "Escalate unresolved issues to a human agent."

Green check icon "Use a polite tone in all responses."

Green check icon "Ask for clarification if the request is vague."

Focus on behavior

Green check icon "Don't make assumptions if the user’s intent is unclear."

Green check icon “Summarize long responses when possible.”

Define boundaries

Green check icon “Do not give legal, financial, or medical advice.”

What to avoid

Don’t be vague

Red cross icon "Always try your best"

Red cross icon "Be helpful"

Red cross icon "Be friendly" (unless part of a task, like a greeting)

Don’t use unsupported logic

Red cross icon "Only respond this way if the user sounds confused"

Red cross icon "Adjust tone based on user emotion"

Don’t include conflicting rules

Red cross icon "Keep responses short" + "Always provide detailed answers"