# Best Practices for Agent System Prompts

The behavior and quality of an agent in AI Agent Foundry depend heavily on its **System Prompt**. This guide outlines best practices for designing effective prompts to ensure your agent performs as intended.

Disclaimer & Model Priority
1. **No Guarantee of Execution**: These guidelines are best practices based on empirical experience. Large Language Models (LLMs) are probabilistic by nature; therefore, the same prompt may not always yield identical results. These practices do not guarantee specific behaviors or outputs.
2. **Provider Documentation Takes Precedence**: Prompt engineering is an evolving field. Official documentation from the model provider (e.g., [Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices) by Anthropic) always supersedes the contents of this guide.


## 1. Basic Format and Structure

We strongly recommend using **Markdown** for your System Prompt. Using headings and bullet points creates a clear structure that helps the AI understand the intent and priority of instructions.

### Recommended Template

Use the following structure as a template to prevent missing instructions and stabilize agent performance.


```markdown
# [Agent Name] Agent Prompt

## Role
[Define the agent's role, persona, and objective concisely.]
Example: You are an expert Data Analyst. You write SQL queries to answer questions from the marketing department.

## Tool Usage
[Provide supplementary instructions on how/when to use specific tools.]
*Note: Detailed technical specifications should be defined in the tool's description settings, but high-level logic goes here.*

## Input / Output
### Input Variables
- `{{variable_name}}`: [Description of the variable]

### Output Goals
- [Definition of the final deliverable]

## Task Flow
1. [Task Name]
   - [Specific steps and decision criteria]
2. [Task Name]
   - [Specific steps and decision criteria]

## Constraints & Rules
- [Prohibitions and constraints]
- [Tone and Manner instructions]
```

## 2. Writing the "Task Flow"

The `Task Flow` section is the most critical part of the prompt. It defines the step-by-step logic the agent should follow.

* **Use Numbered Lists**: Numbering steps (`1.`, `2.`) helps the AI recognize the chronological order of execution.
* **Be Specific**: Avoid vague instructions like "Analyze the data." Instead, specify the tool and action: "Check columns using the `list_columns` tool, then execute..."
* **Set Checkpoints**: Include conditions like "Verify X before proceeding to the next step" to prevent skipped steps and reduce hallucinations.


## 3. Practical Snippets (Tips)

Below are specific instruction snippets to control output formats and behavior. These are best placed in the **Tool Description** of the relevant tool or the **Constraints** section of the System Prompt.

### A. Enhancing Plotly Chart Quality

*Recommended placement: **Tool Description** (for the visualization tool)*

To ensure consistent color schemes and prevent layout overlap when generating charts:


```text
Provide visualization for analysis result by rendering charts using Plotly.js.
- Use the color scheme: [ "B4E3E3", "ABB3DB", "D9BFDF", "F8E1B0", "8FD6D4", "828DCA", "C69ED0", "F5D389", "6AC8C6", "5867B8", "B37EC0", "F1C461", "44BAB8", "2E41A6", "8CC97E", "A05EB0" ]
- For charts with more than three categories, actively use updatemenus
- When summarizing multiple analysis, combine relevant charts into a single dashboard using Plotly's grid layout (e.g., grid: {rows: 2, columns: 2, pattern: 'independent'}) and ensure no elements overlap
- Prevent text overlap by:
    * Include adequate margins: {l: 80, r: 80, t: 100, b: 80}
    * For pie charts with small segments (<5%), use textinfo: 'none' and rely on legend instead of labels
    * Set minimum dashboard dimensions: height: 600, width: 1000
    * For grid layouts, use wider domain spacing with 0.1 gap: [0, 0.45] and [0.55, 1]
```

### B. Suppressing React Component Errors

*Recommended placement: **Tool Description** (for the UI generation tool)*

To prevent errors caused by importing unsupported libraries when generating React UI:


```text
Generates React components with Tailwind CSS.
ENVIRONMENT CONSTRAINTS:
1. Charts: react-plotly.js is the ONLY installed library. recharts is NOT installed (do not import).
2. Icons: lucide-react is NOT installed; use inline <svg> tags only.
3. UI: Static view only. NO <button> or <a> tags (no download/details actions). Single file, export default.
```

### C. Language and Tone Control

*Recommended placement: **System Prompt** (Role or Constraints section)*

To ensure the agent adapts to the user's language and maintains a professional demeanor:


```text
Language: Communicate in User's Detected Language. Tell the detected language to target agent when you call.
Tone: Always maintain polite and respectful language, even if the user requests slang or profanity.
```

## 4. System Limitations & Constraints

When designing your agent, keep the following system constraints in mind:

* **Character Limit (9,000 chars)**: The System Prompt has a limit of approximately 9,000 characters. Do not include large manuals or knowledge bases directly in the prompt. Instead, store them in a **Text Knowledge Base** and instruct the agent to search it when needed.
* **Data Analysis Limits**:
  * **Row Limit**: The default number of rows retrieved in a single SQL execution is **50** (Max: 100).
  * **Timeout**: The default SQL timeout is **60 seconds** (Max: 300s). Optimize queries to avoid timeouts.
  * **Column Search**: Tools like `search_schema` can only retrieve up to **20 columns** at a time. If investigating wide tables, explicitly instruct the agent in the `Task Flow` to split the investigation into smaller batches.
* **Sub-Agents**: For complex workflows, avoid doing everything in one agent. Split tasks into specialized **Sub-Agents** (e.g., one for SQL generation, one for Report writing). This keeps the context clean and improves accuracy.