Building Your Agent
Instructions
Write the rules that tell your agent how to behave, what to say, and when to step back
Writing your agent's instructions is like handing a new team member a job description: the clearer you are about the role, the tone, and the rules, the better they do the job. Instructions are the most important part of setting up your agent. They decide how it behaves — its personality, tone, rules, limits, and how it makes decisions. The more specific you are, the better your agent performs.
What instructions control
| Aspect | What you define |
|---|---|
| Personality | The agent's tone, style, and character ("friendly and casual" vs. "formal and professional") |
| Scope | What the agent should and shouldn't do ("only answer questions about our products") |
| Behavior rules | How to handle specific situations ("if someone asks about pricing, always include the link to our pricing page") |
| Response format | How answers should look ("use bullet points", "keep answers under three sentences") |
| Tool usage | When and how to use a specific tool ("always check the calendar before suggesting a meeting time") |
| Escalation | When to hand off to a person ("if someone asks to cancel their account, say you'll connect them with support") |
Before you start
- Save the Profile section first. Magic Instructions (below) uses your agent's name and description to write better instructions.
- Have a rough idea of what your agent should and shouldn't do — even a few bullet points helps.
Magic Instructions
Don't want to write instructions from scratch? Click the Magic Instructions button and describe what you want your agent to do in plain language. Nirvai writes a complete set of instructions for you — tone, rules, scope, when to hand off to a person, and how to use tools.
You can keep the generated instructions as they are or tweak them. Magic Instructions is the fastest way to get a working agent up and running.
Magic Instructions works best when your agent already has a clear name and description in its Profile. Nirvai uses that to write more relevant instructions.
Writing instructions manually
In the builder, choose Instructions in the left menu. You'll see a large text box where you write your instructions in plain language, with a word count above it.
Instructions
What this agent should do, how it should answer, and anything it must never do.
A structure that works
A good set of instructions follows this pattern:
WHO you are:
Your role and purpose
HOW you respond:
Tone, style, formatting rules
WHAT you do:
The tasks you handle and how
WHAT you don't do:
Boundaries and limits
SPECIAL RULES:
Specific if/then behaviors
Example: customer support agent
You are a customer support agent for Acme Corp. You help customers with product questions, order tracking, and returns.
Tone: Be friendly, helpful, and patient. Use simple language — avoid jargon.
Rules:
- Always greet the user and ask how you can help
- When asked about an order, use the order lookup tool to find the status
- For return requests, explain our 30-day return policy and provide the return form link
- If you don't know the answer, say so honestly — don't make things up
- Never share internal pricing, discount codes, or employee information
- If the user is frustrated, acknowledge their concern before solving the problem
Escalation: If the customer asks to speak with a human, or if the issue involves billing disputes, say: "I'll connect you with our support team right away" and end the conversation politely.
Example: research agent
You are a research assistant that helps users find and summarize information on specific topics.
How to work:
- Always use web search to find current information — don't rely on old knowledge
- Cite your sources with links when possible
- Present findings in a clear order: summary first, then details
- If asked to compare topics, use a table
Limits:
- Don't give medical, legal, or financial advice
- If a topic is too broad, ask the user to narrow it down before researching
Common mistakes
| Mistake | Problem | Better approach |
|---|---|---|
| Vague instructions like "be helpful" | The agent doesn't know what "helpful" means in your situation | "Answer product questions using the documents in your project. Keep responses under three sentences." |
| No boundaries | The agent tries to answer everything, including things it shouldn't | "Only answer questions about our products. For anything else, say: I can only help with product questions." |
| Contradictory rules | The agent gets confused and behaves inconsistently | Read your instructions for conflicts before you save |
| Instructions that are too long | Important rules get lost in the noise | Keep instructions focused. Put reference material in a project instead. |
| No way to escalate | People get stuck when the agent can't help | Always say when and how to hand off to a person |
Using values from earlier steps
If your agent runs inside an automation (a chain of steps that run one after another), it can use the result of a previous step as its input. For example:
Analyze the customer feedback provided in the input. Sort it as positive, negative, or neutral. Rate the urgency from 1 to 5.
The automation hands the previous step's result to your agent as its input, so your instructions should describe what to do with that input.
Testing your instructions
The best way to check your instructions is to chat with your agent after you create it:
- Ask the kinds of questions your users will ask.
- Try edge cases — questions outside what the agent is meant to handle.
- Check that the tone and format match what you described.
- Confirm the agent uses tools the way your rules say it should.
If the agent doesn't behave as expected, edit the instructions and test again. It often takes two or three rounds to get them right.
Turn on Learns from your feedback and tell the agent what went wrong in chat — it proposes the fix to its instructions, and you approve it.
Troubleshooting
| Problem | Fix |
|---|---|
| The agent ignores a rule I wrote | Make the rule shorter and more specific, and put it near the top. Long instructions can bury important rules. |
| The agent answers questions it shouldn't | Add a clear scope and boundary ("only answer questions about X; for anything else, say…"). |
| Magic Instructions gives generic results | Fill in a clear name and description in the Profile section first, then generate again. |
| Responses are too long or off-tone | Spell out the format and tone ("keep answers under three sentences", "be warm and casual") and test again. |
What's next
Once it has a profile and instructions, your agent is Ready. Next, give it actions with Tools.