How do I write good instructions for my AI agent?

Agent instructions are like a job description - they define what your agent should do, how it should behave, and provide necessary context. Here's how to write effective instructions.

Two Ways to Create Instructions

Direct editing - Click "Instructions" in the agent navbar to write and edit directly
Conversational configuration - Chat with the agent and ask it to update its own instructions based on the conversation

The Recommended Workflow

Start a conversation - Describe what you want in plain language, like onboarding a new team member
Agent asks for what it needs - It will request capabilities, documents, or clarification
Agent drafts instructions - Writes its own instructions from the conversation for your review
Review and tweak - Read the draft, make adjustments, and approve
Iterate over time - Return anytime to improve

Best Practices

Do:

Be specific about the expected outcome
Explain the "why" behind important rules
Provide examples of good and bad behavior
Define escalation paths for edge cases

Don't:

Write novel-length instructions upfront
Assume the agent will infer unstated requirements
Include irrelevant context
Forget to update instructions as needs change

The Intern Analogy

Think of setting up an agent like onboarding a new intern:

Explain the job and the goal
Provide context and resources
Set boundaries - what should they never do?
Start supervised and monitor their work
Gradually expand responsibility as trust is earned

Version Control

Agent instructions are automatically versioned, so you can:

Track changes over time
Revert to previous versions if needed
Compare versions side-by-side