Crafting Effective Instructions for Declarative Agents

Your instructions are your agent. With declarative agents, you don’t write code to control behavior. You write instructions, and the quality of those instructions is the single biggest factor in whether your agent feels like a purpose-built assistant or a fancy search bar. This post covers the 5-part instruction framework I use every time I build a declarative agent.

Why Instructions Are Everything

Think of instructions like an onboarding document for a new employee. You wouldn’t just hire someone and say “help people with HR stuff.” You’d say: “You’re the go-to person for new hires. You cover benefits, IT setup, and onboarding checklists. You don’t handle payroll disputes; send those to the HR Business Partner. Be friendly but professional.”

Your agent needs that same clarity. Without it, the model guesses, and when a language model guesses, it tends to be confidently generic, which is the worst kind of wrong.

Your instructions live in appPackage/instructions.txt, referenced from your declarativeAgent.json. It’s just a text file with no special syntax, no DSL, no markup, but it’s the most important file in your entire agent project.

The 5-Part Instruction Framework

Each part answers a specific question the model needs answered to behave well.

1. Role: “Who am I?”

Start with one clear sentence about who this agent is. This anchors every response. The model now knows it’s not a general assistant; it’s a specialist.

You are the Zava Insurance HR Onboarding Buddy, a friendly and professional
AI assistant dedicated to helping new employees navigate their first weeks
at Zava Insurance.

One sentence. Without a role, the agent treats every question as a general knowledge query. With a role, it filters responses through the lens of “I’m an onboarding specialist at Zava Insurance.”

2. Tone & Personality: “How should I sound?”

Define the emotional register you want.

Be warm, encouraging, and welcoming: starting a new job is exciting but
can be overwhelming. Use a conversational, approachable tone while remaining
professional. Use emoji sparingly: one in a welcome message is great,
emoji in every sentence is not.

An agent that sounds cold and clinical when a nervous new hire asks about benefits creates a terrible first impression. And without emoji guidance, some models go wild; set expectations early to avoid emoji overload in production.

3. Scope: “What do I help with?”

Explicitly list what the agent covers. Being explicit about what’s in-bounds implicitly tells the model what’s out-of-bounds.

You help with the following topics:
- Onboarding logistics and first-week checklists
- Benefits enrollment and company policies
- IT and equipment setup (laptop, accounts, badge access)
- Organizational structure and team introductions
- Onboarding task tracking and progress
- Creating support requests for unresolved issues

4. Guardrails: “What must I never do?”

Guardrails are the hard rules your agent must always follow, no matter what the user asks.

- Never provide legal advice: direct users to the Legal team
- Never discuss compensation, salary bands, or pay equity: direct users
  to the HR Business Partner
- Never fabricate information: if you don't know the answer, say so and
  suggest who to contact
- Never share other employees' personal information

I write these as “never” statements deliberately; the model respects that phrasing more strongly than softer language like “try to avoid” or “prefer not to.” Without guardrails, your agent will eventually answer a question it shouldn’t. Someone will ask about salary ranges, and the model will happily generate a plausible-sounding but fabricated answer.

5. Response Guidelines: “How should I format my answers?”

Without response guidelines, you’ll get inconsistent formatting, sometimes a wall of text, sometimes an elaborate essay when a bullet list would do.

- Keep responses concise: 2 to 4 short paragraphs maximum
- Use bullet points for multi-step instructions or lists
- When referencing company documents, cite them by name
- If you can't fully answer a question, acknowledge what you know,
  state what you don't, and suggest where to find the complete answer

Putting It All Together

Here’s the complete Zava Insurance HR Onboarding Buddy instructions with all five parts combined:

You are the Zava Insurance HR Onboarding Buddy, a friendly and professional
AI assistant dedicated to helping new employees navigate their first weeks
at Zava Insurance.

Be warm, encouraging, and welcoming: starting a new job is exciting but
can be overwhelming. Use a conversational, approachable tone while remaining
professional. Use emoji sparingly.

You help with the following topics:
- Onboarding logistics and first-week checklists
- Benefits enrollment and company policies
- IT and equipment setup
- Organizational structure and team introductions
- Onboarding task tracking and progress
- Creating support requests for unresolved issues

Guardrails:
- Never provide legal advice: direct users to the Legal team
- Never discuss compensation or salary bands: direct to the HR Business Partner
- Never fabricate information: if you don't know, say so
- Never share other employees' personal information

Response guidelines:
- Keep responses concise: 2 to 4 short paragraphs max
- Use bullet points for multi-step instructions
- Cite source documents by name
- If unsure, acknowledge it and suggest where to find the answer

Notice how the entire thing fits in about 25 lines. You don’t need a novel. You need clarity.

Bad Instructions vs. Good Instructions

A new hire asks the agent: “What’s the salary range for a Senior Engineer?”

With vague instructions like “You are a helpful HR assistant”:

The agent made up numbers. It sounds confident. It’s completely wrong.

With our 5-part framework:

The guardrails kicked in. The agent stayed in character, declined gracefully, and redirected to the right person. That’s an agent you can trust in production.

The Value You Gain

With well-crafted instructions, your declarative agent goes from “generic chatbot” to “purpose-built assistant” in minutes. You get:

• Consistency: The agent responds in the same voice and style every time
• Safety: Guardrails prevent the agent from wandering into dangerous territory
• Trust: Users quickly learn what the agent can and can’t do, which builds confidence
• Discoverability: A clear scope (combined with conversation starters) helps users understand the agent’s value immediately

All of this without writing a single line of code, just thoughtful writing in a text file.

Resources

• Writing Effective Instructions for Declarative Agents
• Declarative Agents for Microsoft 365 Copilot Overview
• Microsoft 365 Agents Toolkit Documentation
• Microsoft 365 Agents Toolkit VS Code Extension
• Declarative Agent Manifest Schema