Ask AI
All Categories
Advanced Features
Writing Effective Instructions

Writing Effective Instructions

Best practices for writing agent instructions that are clear, safe, and task-focused.

Instructions

The Instructions field in the AI Agent node defines the agent’s role, logic, and behavior. It controls how the agent responds to input and when it uses tools.

Well-structured instructions are essential for consistent and predictable results.

Structure

Effective instructions typically include:

  • A clear role description
  • Conditions for calling tools
  • Fallback behavior for missing data
  • Specific phrases to use in responses
Notion image

Example

Let’s create an assistant that handles refund requests.

This agent should:

  • Listen for refund-related messages
  • Use the initiate_refund tool (which submits a refund request to the backend)
  • Require both an email and order ID to proceed
  • Ask for missing data if needed
  • Ignore unrelated input
Notion image

📌 Tip: Reference tools clearly in your instructions

The agent doesn't "see" what each tool does — it relies on:

  • the tool’s name
  • the description field (in the tool node)
  • and what you say about it in the instructions

To make the right decisions, your instructions must clearly explain when and why to use each tool.

✅ Good example:

You are a travel assistant. Use the get_flights tool to search for flights. Use the get_weather tool only when the user asks about the weather in a specific location. Always confirm the city and date before calling either tool.

❌ Poor example:

You are a travel assistant. Help the user with their request.

(This leaves the agent guessing — what tools are available? When should they be used? What inputs are required?)

Best Practices

  • Focus on one task or role per agent
  • Add conditions to handle incomplete input
  • Clearly explain which tool to use and in what case
  • Restrict agent behavior to prevent unwanted replies
  • Specify tone and wording explicitly

Common Patterns

  • Ask for missing data:

      • If [required field] is not provided, ask the user to supply it before proceeding.

  • Confirm actions:

      • After calling [tool], respond: "Your request has been submitted."

  • Reject unrelated input:

      • If the message is not related to [task], reply: "Sorry, I can't help with that."

 
Did this answer your question?
😞
😐
🤩
Agent Design Foundations Tool Design for AI Agents