BC Agent Instructions Skill

Single source of truth for writing the natural-language instructions that guide Business Central agents. These instructions tell the agent runtime how to navigate the UI, read/set fields, invoke actions, and communicate with users.

For SDK architecture and how instructions are loaded see skill-agent-toolkit. For task-creation patterns (Public API, attachments, multi-turn) see skill-agent-task-patterns.

Storage modes

References:

• Write effective instructions
• Instruction keywords
• Best practices

Key facts about the runtime

• Instructions are the PRIMARY lever for controlling agent behavior
• The runtime has specific tools: field setting, lookups, action invocation, page navigation, email composition
• Instructions must use specific keywords to activate these tools effectively
• Only English is fully supported — safeguards are optimized for English
• Shorter, well-structured instructions often outperform verbose ones
• The agent retains action history but NOT page state — use MEMORIZE

Framework: Responsibilities → Guidelines → Instructions

Every instruction file follows this three-part structure.

1. RESPONSIBILITY (one line)

A single sentence defining the agent's accountability. Anchors all behavior.

**RESPONSIBILITY**: {What the agent is accountable for — one sentence}

Rules:

• One sentence only — no paragraphs
• State the business outcome, not technical implementation
• Include the key domain nouns ("leads", "sales orders", "credit checks")

2. GUIDELINES (cross-task rules)

Rules that apply across all tasks.

**GUIDELINES**:
- ALWAYS {mandatory behavior}
- DO NOT {prohibited action}
- ALWAYS {safety/review gate}

Rules:

• ALWAYS (bold) for mandatory behaviors
• DO NOT (bold) for prohibited actions
• Gate ALL critical actions (posting, sending, releasing, deleting) with user intervention
• Include data access boundaries (read-only vs. read-write)
• Include reply/output keywords the agent should use for structured responses
• Keep to 3-7 guidelines — more causes confusion

3. INSTRUCTIONS (step-by-step per task)

Ordered steps for each task, using runtime keywords.

**INSTRUCTIONS**:

## Task: {Task Name}

1. {Action using keyword}
   a. {Sub-step with detail}
   b. {Sub-step with detail}
2. If {condition}: {action}
   a. **DO NOT** {prohibited action in this context}
3. {Next action}

Rules:

• One ## Task: section per distinct workflow
• Numbered steps with lettered sub-steps
• Use official keywords (table below) to activate runtime tools
• Place MEMORIZE BEFORE the value is needed in later steps
• Include error handling at the end of each task
• Provide example formats for memorized data

Official runtime keywords

Critical keyword rules:

• Page, field, and action names MUST match exactly what the agent sees in its profile
• MEMORIZE must include an example format: **Memorize**: "Customer: ACME Corp | Credit: 50,000"
• Reply keywords should include structured output patterns for programmatic parsing
• The agent does NOT have access to "Tell Me" — all navigation must be via explicit page names

Step-by-step creation workflow

1. Gather inputs: agent purpose (1 sentence), pages in scope, fields to read/write, actions to invoke, decision criteria, output format, safety gates
2. Draft RESPONSIBILITY: one sentence with domain + outcome
3. Draft GUIDELINES: 3-7 rules — at least one ALWAYS, one DO NOT, one safety gate
4. Draft INSTRUCTIONS per task: navigate → read+MEMORIZE → branch → execute → Reply
5. Validate with the checklist below
6. Test and iterate: deploy → observe timeline → refine. Simpler instructions often perform better.

Validation checklist

• Page names match agent profile and page customizations exactly
• Field names match the fields visible on the agent's pages exactly
• Action names match the action captions visible on the agent's pages
• MEMORIZE placed BEFORE the memorized value is needed in later steps
• MEMORIZE includes example format (e.g., "Key: value | Key: value")
• All critical actions (posting, sending, releasing, deleting) gated by user intervention or review
• Written in English — agent safeguards are optimized for English
• Environment-agnostic — no hardcoded company names, URLs, user IDs
• Concise — no redundant prose; each line serves a purpose
• Error handling section covers: not found, unavailable pages, failed actions
• Reply formats use consistent keywords for structured parsing
• No references to "Tell Me" (agents cannot use it)
• Guidelines count is 3-7 (not too few, not too many)
• Each task has numbered steps with lettered sub-steps

Anti-patterns

Advanced concepts

Page-specific dynamic instructions

For SDK agents, IAgentTaskExecution.GetAgentTaskPageContext injects dynamic context per page using Liquid-style conditionals:

Consider the following fields:
{% if page.id == 42 %}
Field "The Answer" — the meaning of the universe
{% else %}
Field "Business Data" — standard business field
{% endif %}

Multi-task instructions

When an agent handles multiple tasks, create separate ## Task: sections. The agent selects the task based on input message content. Use distinct keywords in the Reply for programmatic routing:

## Task: Qualify Lead
...Reply: "qualification successful | ..."

## Task: Re-evaluate Lead
...Reply: "re-evaluation complete | ..."

Agent-to-agent handoff

When one agent creates tasks for another:

• Verify the target agent is configured (check setup fields)
• Use page actions that trigger task creation (the action handles the API call)
• MEMORIZE the handoff result for the final reply
• Include fallback instructions if the handoff action is unavailable

Examples

Load an example only when you need a concrete template:

• When writing a minimal single-task agent, see Simple instructions (credit check).
• When building a multi-task agent with handoff and error handling, see Advanced instructions (lead qualifier).
• If you need to look up a runtime keyword, see Keywords reference.